Directives

Directives define specific behaviors that can be applied to fields or types within a GraphQL schema.

Data Connect Defined

@auth on QUERY | MUTATION

The @auth directive defines the authentication policy for a query or mutation.

It must be added to any operation that you wish to be accessible from a client application. If not specified, the operation defaults to @auth(level: NO_ACCESS).

Refer to Data Connect Auth Guide for the best practices.

@check on QUERY | MUTATION | FIELD | FRAGMENT_DEFINITION | FRAGMENT_SPREAD | INLINE_FRAGMENT

Ensure this field is present and is not null or [], or abort the request / transaction.

A CEL expression, expr is used to test the field value. It defaults to rejecting null and [] but a custom expression can be provided instead.

If the field occurs multiple times (i.e. directly or indirectly nested under a list), expr will be executed once for each occurrence and @check succeeds if all values succeed. @check fails when the field is not present at all (i.e. all ancestor paths contain null or []), unless optional is true.

If a @check fails in a mutation, the top-level field containing it will be replaced with a partial error, whose message can be customzied via the message argument. Each subsequent top-level fields will return an aborted error (i.e. not executed). To rollback previous steps, see @transaction.

@col on FIELD_DEFINITION

Customizes a field that represents a SQL database table column.

Data Connect maps scalar Fields on @table type to a SQL column of corresponding data type.

• scalar UUID maps to uuid.
• scalar String maps to text.
• scalar Int maps to int.
• scalar Int64 maps to bigint.
• scalar Float maps to double precision.
• scalar Boolean maps to boolean.
• scalar Date maps to date.
• scalar Timestamp maps to timestamptz.
• scalar Any maps to jsonb.
• scalar Vector maps to pgvector.

Array scalar fields are mapped to Postgres arrays.

Example: Serial Primary Key

For example, you can define auto-increment primary key.

type Post @table {
  id: Int! @col(name: "post_id", dataType: "serial")
}

Data Connect converts it to the following SQL table schema.

CREATE TABLE "public"."post" (
  "post_id" serial NOT NULL,
  PRIMARY KEY ("id")
)

Example: Vector

type Post @table {
  content: String! @col(name: "post_content")
  contentEmbedding: Vector! @col(size:768)
}

@default on FIELD_DEFINITION

Specifies the default value for a column field.

For example:

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  number: Int! @col(dataType: "serial")
  createdAt: Date! @default(expr: "request.time")
  role: String! @default(value: "Member")
  credit: Int! @default(value: 100)
}

The supported arguments vary based on the field type.

@index on FIELD_DEFINITION | OBJECT

Defines a database index to optimize query performance.

type User @table @index(fields: ["name", "phoneNumber"], order: [ASC, DESC]) {
    name: String @index
    phoneNumber: Int64 @index
    tags: [String] @index # GIN Index
}

Single Field Index

You can put @index on a @col field to create a SQL index.

@index(order) matters little for single field indexes, as they can be scanned in both directions.

Composite Index

You can put @index(fields: [...]) on @table type to define composite indexes.

@index(order: [...]) can customize the index order to satisfy particular filter and order requirement.

@redact on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

Redact a part of the response from the client.

Redacted fields are still evaluated for side effects (including data changes and @check) and the results are still available to later steps in CEL expressions (via response.fieldName).

@ref on FIELD_DEFINITION

Defines a foreign key reference to another table.

For example, we can define a many-to-one relation.

type ManyTable @table {
  refField: OneTable!
}
type OneTable @table {
  someField: String!
}

Data Connect adds implicit foreign key column and relation query field. So the above schema is equivalent to the following schema.

type ManyTable @table {
  id: UUID! @default(expr: "uuidV4()")
  refField: OneTable! @ref(fields: "refFieldId", references: "id")
  refFieldId: UUID!
}
type OneTable @table {
  id: UUID! @default(expr: "uuidV4()")
  someField: UUID!
  # Generated Fields:
  # manyTables_on_refField: [ManyTable!]!
}

Data Connect generates the necessary foreign key constraint.

CREATE TABLE "public"."many_table" (
  "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
  "ref_field_id" uuid NOT NULL,
  PRIMARY KEY ("id"),
  CONSTRAINT "many_table_ref_field_id_fkey" FOREIGN KEY ("ref_field_id") REFERENCES "public"."one_table" ("id") ON DELETE CASCADE
)

Example: Traverse the Reference Field

query ($id: UUID!) {
  manyTable(id: $id) {
    refField { id }
  }
}

Example: Reverse Traverse the Reference field

query ($id: UUID!) {
  oneTable(id: $id) {
    manyTables_on_refField { id }
  }
}

Optional Many-to-One Relation

An optional foreign key reference will be set to null if the referenced row is deleted.

In this example, if a User is deleted, the assignee and reporter references will be set to null.

type Bug @table {
  title: String!
  assignee: User
  reproter: User
}

type User @table { name: String!  }

Required Many-to-One Relation

A required foreign key reference will cascade delete if the referenced row is deleted.

In this example, if a Post is deleted, associated comments will also be deleted.

type Comment @table {
  post: Post!
  content: String!
}

type Post @table { title: String!  }

Many To Many Relation

You can define a many-to-many relation with a join table.

type Membership @table(key: ["group", "user"]) {
  group: Group!
  user: User!
  role: String! @default(value: "member")
}

type Group @table { name: String! }
type User @table { name: String! }

When Data Connect sees a table with two reference field as its primary key, it knows this is a join table, so expands the many-to-many query field.

type Group @table {
  name: String!
  # Generated Fields:
  # users_via_Membership: [User!]!
  # memberships_on_group: [Membership!]!
}
type User @table {
  name: String!
  # Generated Fields:
  # groups_via_Membership: [Group!]!
  # memberships_on_user: [Membership!]!
}

Example: Traverse the Many-To-Many Relation

query ($id: UUID!) {
  group(id: $id) {
    users: users_via_Membership {
      name
    }
  }
}

Example: Traverse to the Join Table

query ($id: UUID!) {
  group(id: $id) {
    memberships: memberships_on_group {
      user { name }
      role
    }
  }
}

One To One Relation

You can even define a one-to-one relation with the help of @unique or @table(key).

type User @table {
  name: String
}
type Account @table {
  user: User! @unique
}
# Alternatively, use primary key constraint.
# type Account @table(key: "user") {
#   user: User!
# }

Example: Transerse the Reference Field

query ($id: UUID!) {
  account(id: $id) {
    user { id }
  }
}

Example: Reverse Traverse the Reference field

query ($id: UUID!) {
  user(id: $id) {
    account_on_user { id }
  }
}

Customizations

• @ref(constraintName) can customize the SQL foreign key constraint name (table_name_ref_field_fkey above).
• @ref(fields) can customize the foreign key field names.
• @ref(references) can customize the constraint to reference other columns. By default, @ref(references) is the primary key of the @ref table. Other fields with @unique may also be referred in the foreign key constraint.

@table on OBJECT

Defines a relational database table.

In this example, we defined one table with a field named myField.

type TableName @table {
  myField: String
}

Data Connect adds an implicit id primary key column. So the above schema is equivalent to:

type TableName @table(key: "id") {
  id: String @default(expr: "uuidV4()")
  myField: String
}

Data Connect generates the following SQL table and CRUD operations to use it.

CREATE TABLE "public"."table_name" (
  "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
  "my_field" text NULL,
  PRIMARY KEY ("id")
)

• You can lookup a row: query ($id: UUID!) { tableName(id: $id) { myField } }
• You can find rows using: query tableNames(limit: 20) { myField }
• You can insert a row: mutation { tableName_insert(data: {myField: "foo"}) }
• You can update a row: mutation ($id: UUID!) { tableName_update(id: $id, data: {myField: "bar"}) }
• You can delete a row: mutation ($id: UUID!) { tableName_delete(id: $id) }

Customizations

• @table(singular) and @table(plural) can customize the singular and plural name.
• @table(name) can customize the Postgres table name.
• @table(key) can customize the primary key field name and type.

For example, the User table often has a uid as its primary key.

type User @table(key: "uid") {
  uid: String!
  name: String
}

• You can securely lookup a row: query { user(key: {uid_expr: "auth.uid"}) { name } }
• You can securely insert a row: mutation { user_insert(data: {uid_expr: "auth.uid" name: "Fred"}) }
• You can securely update a row: mutation { user_update(key: {uid_expr: "auth.uid"}, data: {name: "New Name"}) }
• You can securely delete a row: mutation { user_delete(key: {uid_expr: "auth.uid"}) }

@table type can be configured further with:

• Custom SQL data types for columns. See @col.
• Add SQL indexes. See @index.
• Add SQL unique constraints. See @unique.
• Add foreign key constraints to define relations. See @ref.

@transaction on MUTATION

Require that this mutation always run in a DB transaction.

Mutations with @transaction are guaranteed to either fully succeed or fully fail. If any of the fields within the transaction fails, the entire transaction is rolled back. From a client standpoint, any failure behaves as if the entire request had failed with a request error and execution had not begun.

Mutations without @transaction would execute each root field one after another in sequence. It surfaces any errors as partial field errors, but not impacts the subsequent executions.

The @transaction directive cannot be added to queries for now. Currently, queries cannot fail partially, the response data is not guaranteed to be a consistent snapshot.

@unique on FIELD_DEFINITION | OBJECT

Defines unique constraints on @table.

For example,

type User @table {
    phoneNumber: Int64 @unique
}
type UserProfile @table {
    user: User! @unique
    address: String @unique
}

• @unique on a @col field adds a single-column unique constraint.
• @unique on a @table type adds a composite unique constraint.
• @unique on a @ref defines a one-to-one relation. It adds unique constraint on @ref(fields).

@unique ensures those fields can uniquely identify a row, so other @table type may define @ref(references) to refer to fields that has a unique constraint.

@view on OBJECT

Defines a relational database Raw SQLview.

Data Connect generates GraphQL queries with WHERE and ORDER BY clauses. However, not all SQL features has native GraphQL equivalent.

You can write an arbitrary SQL SELECT statement. Data Connect would map Graphql fields on @view type to columns in your SELECT statement.

• Scalar GQL fields (camelCase) should match a SQL column (snake_case) in the SQL SELECT statement.
• Reference GQL field can point to another @table type. Similar to foreign key defined with @ref on a @table type, a @view type establishes a relation when @ref(fields) match @ref(references) on the target table.

In this example, you can use @view(sql) to define an aggregation view on existing table.

type User @table {
  name: String
  score: Int
}
type UserAggregation @view(sql: """
  SELECT
    COUNT(*) as count,
    SUM(score) as sum,
    AVG(score) as average,
    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY score) AS median,
    (SELECT id FROM "user" LIMIT 1) as example_id
  FROM "user"
""") {
  count: Int
  sum: Int
  average: Float
  median: Float
  example: User
  exampleId: UUID
}

Example: Query Raw SQL View

query {
  userAggregations {
    count sum average median
    exampleId example { id }
  }
}

One-to-One View

An one-to-one companion @view can be handy if you want to argument a @table with additional implied content.

type Restaurant @table {
  name: String!
}
type Review @table {
  restaurant: Restaurant!
  rating: Int!
}
type RestaurantStats @view(sql: """
  SELECT
    restaurant_id,
    COUNT(*) AS review_count,
    AVG(rating) AS average_rating
  FROM review
  GROUP BY restaurant_id
""") {
  restaurant: Restaurant @unique
  reviewCount: Int
  averageRating: Float
}

In this example, @unique convey the assumption that each Restaurant should have only one RestaurantStats object.

Example: Query One-to-One View

query ListRestaurants {
  restaurants {
    name
    stats: restaurantStats_on_restaurant {
      reviewCount
      averageRating
    }
  }
}

Example: Filter based on One-to-One View

query BestRestaurants($minAvgRating: Float, $minReviewCount: Int) {
  restaurants(where: {
    restaurantStats_on_restaurant: {
      averageRating: {ge: $minAvgRating}
      reviewCount: {ge: $minReviewCount}
    }
  }) { name }
}

Customizations

• One of @view(sql) or @view(name) should be defined. @view(name) can refer to a persisted SQL view in the Postgres schema.
• @view(singular) and @view(plural) can customize the singular and plural name.

@view type can be configured further:

• @unique lets you define one-to-one relation.
• @col lets you customize SQL column mapping. For example, @col(name: "column_in_select").

Limitations

Raw SQL view doesn't have a primary key, so it doesn't support lookup. Other @table or @view cannot have @ref to a view either.

View cannot be mutated. You can perform CRUD operations on the underlying table to alter its content.

Important: Data Connect doesn't parse and validate SQL

• If the SQL view is invalid or undefined, related requests may fail.
• If the SQL view return incompatible types. Firebase Data Connect may surface errors.
• If a field doesn't have a corresponding column in the SQL SELECT statement, it will always be null.
• There is no way to ensure VIEW to TABLE @ref constraint.
• All fields must be nullable in case they aren't found in the SELECT statement or in the referenced table.

Important: You should always test @view!

Built In

@deprecated on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE

Marks an element of a GraphQL schema as no longer supported.

@include on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

Directs the executor to include this field or fragment only when the if argument is true.

@skip on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

Directs the executor to skip this field or fragment when the if argument is true.

@specifiedBy on SCALAR

Exposes a URL that specifies the behavior of this scalar.