Configuration & Customization

Extra configuration options can be set on SQL entities using comment directives.

Comment Directives

Comment directives are snippets of configuration associated with SQL entities that alter how those entities behave.

The format of a comment directive is

1
@graphql(<JSON>)

Inflection

Inflection describes how SQL entities' names are transformed into GraphQL type and field names. By default, inflection is disabled and SQL names are literally interpolated such that

1
create table "BlogPost"(
2
    id int primary key,
3
    ...
4
);

results in GraphQL type names like

1
BlogPost
2
BlogPostEdge
3
BlogPostConnection
4
...

Since snake case is a common casing structure for SQL types, pg_graphql support basic inflection from snake_case to PascalCase for type names, and snake_case to camelCase for field names to match Javascript conventions.

The inflection directive can be applied at the schema level with:

1
comment on schema <schema_name> is e'@graphql({"inflect_names": true})';

for example

1
comment on schema public is e'@graphql({"inflect_names": true})';
2
3
create table blog_post(
4
    id int primary key,
5
    ...
6
);

similarly would generated the GraphQL type names

1
BlogPost
2
BlogPostEdge
3
BlogPostConnection
4
...

For more fine grained adjustments to reflected names, see renaming.

Max Rows

The default page size for collections is 30 entries. To adjust the number of entries on each page, set a max_rows directive on the relevant schema entity, table or view.

For example, to increase the max rows per page for each table in the public schema:

1
comment on schema public is e'@graphql({"max_rows": 100})';

To limit the max rows per page for the blog_post table and Person view:

1
comment on table blog_post is e'@graphql({"max_rows": 20})';
2
comment on view "Person" is e'@graphql({"primary_key_columns": ["id"], "max_rows": 10})';

The max_rows value falls back to the parent object if it is missing on the current object. For example, if a table doesn't have max_rows set, the value set on the table's schema will be used. If the schema also doesn't have max_rows set, then it falls back to default value 30. The parent object of a view is the schema, not the table on which the view is created.

totalCount

totalCount is an opt-in field that extends a table's Connection type. It provides a count of the rows that match the query's filters, and ignores pagination arguments.

1
type BlogPostConnection {
2
  edges: [BlogPostEdge!]!
3
  pageInfo: PageInfo!
4
5
  """The total number of records matching the `filter` criteria"""
6
  totalCount: Int! # this field
7
}

to enable totalCount for a table, use the directive

1
comment on table "BlogPost" is e'@graphql({"totalCount": {"enabled": true}})';

for example

1
create table "BlogPost"(
2
    id serial primary key,
3
    email varchar(255) not null
4
);
5
comment on table "BlogPost" is e'@graphql({"totalCount": {"enabled": true}})';

Aggregate

The aggregate field is an opt-in field that extends a table's Connection type. It provides various aggregate functions like count, sum, avg, min, and max that operate on the collection of records that match the query's filters.

1
type BlogPostConnection {
2
  edges: [BlogPostEdge!]!
3
  pageInfo: PageInfo!
4
5
  """Aggregate functions calculated on the collection of `BlogPost`"""
6
  aggregate: BlogPostAggregate # this field
7
}

To enable the aggregate field for a table, use the directive:

1
comment on table "BlogPost" is e'@graphql({"aggregate": {"enabled": true}})';

For example:

1
create table "BlogPost"(
2
    id serial primary key,
3
    title varchar(255) not null,
4
    rating int not null
5
);
6
comment on table "BlogPost" is e'@graphql({"aggregate": {"enabled": true}})';

You can combine both totalCount and aggregate directives:

1
comment on table "BlogPost" is e'@graphql({"totalCount": {"enabled": true}, "aggregate": {"enabled": true}})';

Renaming

Table's Type

Use the "name" JSON key to override a table's type name.

1
create table account(
2
    id serial primary key
3
);
4
5
comment on table public.account is
6
e'@graphql({"name": "AccountHolder"})';

results in:

1
type AccountHolder { # previously: "Account"
2
  id: Int!
3
}

Column's Field Name

Use the "name" JSON key to override a column's field name.

1
create table public."Account"(
2
    id serial primary key,
3
    email text
4
);
5
6
comment on column "Account".email is
7
e'@graphql({"name": "emailAddress"})';

results in:

1
type Account {
2
  nodeId: ID!
3
  id: Int!
4
  emailAddress: String! # previously "email"
5
}

Computed Field

Use the "name" JSON key to override a computed field's name.

1
create table "Account"(
2
    id serial primary key,
3
    "firstName" varchar(255) not null,
4
    "lastName" varchar(255) not null
5
);
6
7
-- Extend with function
8
create function public."_fullName"(rec public."Account")
9
    returns text
10
    immutable
11
    strict
12
    language sql
13
as $$
14
    select format('%s %s', rec."firstName", rec."lastName")
15
$$;
16
17
comment on function public._full_name is
18
e'@graphql({"name": "displayName"})';

results in:

1
type Account {
2
  nodeId: ID!
3
  id: Int!
4
  firstName: String!
5
  lastName: String!
6
  displayName: String # previously "fullName"
7
}

Relationship's Field

Use the "local_name" and "foreign_name" JSON keys to override a relationship's inbound and outbound field names.

1
create table "Account"(
2
    id serial primary key
3
);
4
5
create table "Post"(
6
    id serial primary key,
7
    "accountId" integer not null references "Account"(id),
8
    title text not null,
9
    body text
10
);
11
12
comment on constraint post_account_id_fkey
13
  on "Post"
14
  is E'@graphql({"foreign_name": "author", "local_name": "posts"})';

results in:

1
type Post {
2
  nodeId: ID!
3
  id: Int!
4
  accountId: Int!
5
  title: String!
6
  body: String!
7
  author: Account # was "account"
8
}
9
10
type Account {
11
  id: Int!
12
  posts( # was "postCollection"
13
    after: Cursor,
14
    before: Cursor,
15
    filter: PostFilter,
16
    first: Int,
17
    last: Int,
18
    orderBy: [PostOrderBy!]
19
  ): PostConnection
20
}

Description

Tables, Columns, and Functions accept a description directive to populate user defined descriptions in the GraphQL schema.

1
create table "Account"(
2
    id serial primary key
3
);
4
5
comment on table public.account
6
is e'@graphql({"description": "A User Account"})';
7
8
comment on column public.account.id
9
is e'@graphql({"description": "The primary key identifier"})';

1
"""A User Account"""
2
type Account implements Node {
3
4
  """The primary key identifier"""
5
  id: Int!
6
}

Enum Variant

If a variant of a Postgres enum does not conform to GraphQL naming conventions, introspection returns an error:

For example:

1
create type "Algorithm" as enum ('aead-ietf');

causes the error:

1
{
2
  "errors": [
3
    {
4
      "message": "Names must only contain [_a-zA-Z0-9] but \"aead-ietf\" does not.",
5
    }
6
  ]
7
}

To resolve this problem, rename the invalid SQL enum variant to a GraphQL compatible name:

1
alter type "Algorithm" rename value 'aead-ietf' to 'AEAD_IETF';

or, add a comment directive to remap the enum variant in the GraphQL API

1
comment on type "Algorithm" is '@graphql({"mappings": {"aead-ietf": "AEAD_IETF"}})';

Which both result in the GraphQL enum:

1
enum Algorithm {
2
  AEAD_IETF
3
}

Configuration & Customization

Extra configuration options can be set on SQL entities using comment directives.

Comment Directives#

Inflection#

Max Rows#

totalCount#

Aggregate#

Renaming#

Table's Type#

Column's Field Name#

Computed Field#

Relationship's Field#

Description#

Enum Variant#

Is this helpful?

Comment Directives

Inflection

Max Rows

totalCount

Aggregate

Renaming

Table's Type

Column's Field Name

Computed Field

Relationship's Field

Description

Enum Variant