/firebase-data-connect-basics

Schema Reference

Contents

• Defining Types
• Core Directives
• Relationships
• Data Types
• Enumerations

Defining Types

Types with @table map to PostgreSQL tables. SQL Connect auto-generates an implicit id: UUID! primary key.

type Movie @table {
  # id: UUID! is auto-added
  title: String!
  releaseYear: Int
  genre: String
}

Customizing Tables

type Movie @table(name: "movies", key: "id", singular: "movie", plural: "movies") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String @col(dataType: "varchar(20)")
}

User Table with Auth

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  displayName: String @col(dataType: "varchar(100)")
  createdAt: Timestamp! @default(expr: "request.time")
}

Core Directives

@table

Defines a database table.

@col

Customizes column mapping.

@default

Sets default value for inserts.

Common expressions:

• uuidV4() - Generate UUID
• auth.uid - Current user's Firebase Auth UID
• request.time - Server timestamp

@unique

Adds unique constraint.

type User @table {
  email: String! @unique
}

# Composite unique
type Review @table @unique(fields: ["movie", "user"]) {
  movie: Movie!
  user: User!
  rating: Int
}

@index

Creates database index for query performance.

type Movie @table @index(fields: ["genre", "releaseYear"], order: [ASC, DESC]) {
  title: String! @index
  genre: String
  releaseYear: Int
}

@searchable

Enables full-text search on String fields.

type Post @table {
  title: String! @searchable
  body: String! @searchable(language: "english")
}

# Usage
query SearchPosts($q: String!) @auth(level: PUBLIC) {
  posts_search(query: $q) { id title body }
}

Relationships

One-to-Many (Implicit Foreign Key)

type Post @table {
  id: UUID! @default(expr: "uuidV4()")
  author: User!  # Creates authorId foreign key
  title: String!
}

type User @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String!
  # Auto-generated: posts_on_author: [Post!]!
}

@ref Directive

Customizes foreign key reference.

type Post @table {
  author: User! @ref(fields: "authorId", references: "id")
  authorId: UUID!  # Explicit FK field
}

Cascade behavior:

• Required reference (User!): CASCADE DELETE (post deleted when user deleted)
• Optional reference (User): SET NULL (authorId set to null when user deleted)

One-to-One

Use @unique on the reference field:

type User @table { id: UUID! name: String! }

type UserProfile @table {
  user: User! @unique  # One profile per user
  bio: String
  avatarUrl: String
}

# Query: user.userProfile_on_user

Many-to-Many

Use a join table with composite primary key:

type Movie @table { id: UUID! title: String! }
type Actor @table { id: UUID! name: String! }

type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  actor: Actor!
  role: String!  # Extra data on relationship
}

# Generated fields:
# - movie.actors_via_MovieActor: [Actor!]!
# - actor.movies_via_MovieActor: [Movie!]!
# - movie.movieActors_on_movie: [MovieActor!]!

Data Types

Enumerations

enum Status {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type Post @table {
  status: Status! @default(value: DRAFT)
  allowedStatuses: [Status!]
}

Rules:

• Enum names: PascalCase, no underscores
• Enum values: UPPER_SNAKE_CASE
• Values are ordered (for comparison operations)
• Changing order or removing values is a breaking change

Views (Advanced)

Map custom SQL queries to GraphQL types:

type MovieStats @view(sql: """
  SELECT
    movie_id,
    COUNT(*) as review_count,
    AVG(rating) as avg_rating
  FROM review
  GROUP BY movie_id
""") {
  movie: Movie @unique
  reviewCount: Int
  avgRating: Float
}

# Query movies with stats
query TopMovies @auth(level: PUBLIC) {
  movies(orderBy: [{ rating: DESC }]) {
    title
    stats: movieStats_on_movie {
      reviewCount avgRating
    }
  }
}