pg_graphql

https://supabase.github.io/pg_graphql
Admin
A PostgreSQL extension that enables querying the database with GraphQL using a single SQL function,...
Tokens:76,261
Snippets:566
Trust Score:9.7
Update:16 hours ago
Show doc for...
Tokens:
Raw
### SQL setup for node interface

Source: https://supabase.github.io/pg_graphql/api/

Example table with primary key and additional columns used for the node interface example.

```sql
create table "Blog"(
  id serial primary key,
  name varchar(255) not null,
  description varchar(255),
  "createdAt" timestamp not null,
  "updatedAt" timestamp not null
);
```

--------------------------------

### BigFloat example: SQL setup

Source: https://supabase.github.io/pg_graphql/api/

SQL table creation and insertion for a GeneralLedger with a numeric(10,2) amount.

```SQL
create table "GeneralLedger"(
    id serial primary key,
    amount numeric(10,2)
);

insert into "GeneralLedger"(amount)
values (22.15);
```

--------------------------------

### SQL Setup: Create Blog table

Source: https://supabase.github.io/pg_graphql/api/

SQL to create the Blog table used in the mutation examples. Includes serial primary key, not null name, and timestamp columns with defaults.

```sql
create table "Blog"(
  id serial primary key,
  name varchar(255) not null,
  description varchar(255),
  "createdAt" timestamp not null default now(),
  "updatedAt" timestamp
);
```

--------------------------------

### JSON example: SQL setup and GraphQL schema

Source: https://supabase.github.io/pg_graphql/api/

SQL table creation and insertion for a User with a jsonb column, and the corresponding GraphQL type definition.

```SQL
create table "User"(
    id bigserial primary key,
    config jsonb
);

insert into "User"(config)
values (jsonb_build_object('palette', 'dark-mode'));
```

```GraphQL
type User {
  nodeId: ID!
  id: BigInt!
  config: JSON
}
```

--------------------------------

### Initialize pgrx with PostgreSQL 17

Source: https://supabase.github.io/pg_graphql/installation/

Initializes pgrx to manage its own PostgreSQL 17 installation. This is the easiest way to get started.

```bash
cargo pgrx init --pg17=download
```

--------------------------------

### Example Table with totalCount Enabled

Source: https://supabase.github.io/pg_graphql/configuration/

SQL example creating a table and enabling totalCount with the directive.

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

--------------------------------

### Install documentation dependencies with pip

Source: https://supabase.github.io/pg_graphql/contributing/

Installs mkdocs, themes, and extensions required for building the documentation.

```bash
pip install -r docs/requirements_docs.txt
```

--------------------------------

### Build, install, and run all tests

Source: https://supabase.github.io/pg_graphql/contributing/

Combines the previous two steps to build and install pg_graphql and run all tests in one command.

```bash
$ cargo pgrx install; ./bin/installcheck
```

--------------------------------

### BigInt example: SQL setup and GraphQL schema

Source: https://supabase.github.io/pg_graphql/api/

SQL table creation and insertion for a Person with a bigserial id, and the corresponding GraphQL type definition.

```SQL
create table "Person"(
    id bigserial primary key,
    name text
);

insert into "Person"(name)
values ('J. Bazworth');
```

```GraphQL
type Person {
  nodeId: ID!
  id: BigInt!
  name: String
}
```

--------------------------------

### Start PostgreSQL 17 with pgrx

Source: https://supabase.github.io/pg_graphql/installation/

Starts the PostgreSQL 17 instance managed by pgrx.

```bash
cargo pgrx start pg17
```

--------------------------------

### Serve documentation locally with mkdocs serve

Source: https://supabase.github.io/pg_graphql/contributing/

Starts a local server to serve the documentation, accessible at http://127.0.0.1:8000/pg_graphql/.

```bash
mkdocs serve
```

--------------------------------

### supabase start output with GraphQL endpoint and API keys

Source: https://supabase.github.io/pg_graphql/supabase/

Shows the output of `supabase start` for a local Supabase project. Provides the GraphQL URL, Studio URL, and anon key needed to call the GraphQL API directly.

```bash
> supabase start
...

Started supabase local development setup.

     GraphQL URL: http://localhost:54321/graphql/v1  <-- GraphQL endpoint
          DB URL: ...
      Studio URL: http://localhost:54323             <-- Supabase Studio
    Inbucket URL: ...
      JWT secret: ...
        anon key: eyJhbGciOiJIUzI1...<truncated>     <-- API_KEY
service_role key: ...

```

--------------------------------

### Enable inflection with example table

Source: https://supabase.github.io/pg_graphql/configuration/

Example of enabling inflection on the public schema and creating a snake_case table.

```sql
comment on schema public is e'@graphql({"inflect_names": true})';

create table blog_post(
    id int primary key,
    ...
);
```

--------------------------------

### Example Table with Aggregate Enabled

Source: https://supabase.github.io/pg_graphql/configuration/

SQL example creating a table and enabling the aggregate field with the directive.

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

--------------------------------

### Launch psql with pg_graphql using cargo pgrx run pg16

Source: https://supabase.github.io/pg_graphql/contributing/

Starts a psql prompt with pg_graphql installed for interactive experimentation, reducing the iteration cycle.

```bash
cargo pgrx run pg16
```

--------------------------------

### Launch the demo with docker-compose

Source: https://supabase.github.io/pg_graphql/quickstart/

Start the demo environment using docker-compose. Requires docker-compose. After running, access GraphiQL at http://localhost:4000/.

```bash
docker-compose up
```

--------------------------------

### Install pg_graphql with cargo pgrx install

Source: https://supabase.github.io/pg_graphql/contributing/

Builds pg_graphql from source and installs it into the Postgres instance specified by pg_config. Must be run after any Rust code changes; can be skipped if only SQL test files are modified.

```bash
cargo pgrx install
```

--------------------------------

### Clone and install pg_graphql with cargo pgrx

Source: https://supabase.github.io/pg_graphql/installation/

Clones the pg_graphql repository and installs the extension using cargo pgrx install --release. Requires pgrx to be installed first.

```bash
git clone https://github.com/supabase/pg_graphql.git
cd pg_graphql
cargo pgrx install --release
```

--------------------------------

### Ordering query example and response

Source: https://supabase.github.io/pg_graphql/api/

Example query that orders blog posts by id in descending order with nulls last, and the corresponding response showing the ordered edges.

```graphql
{
  blogCollection(
    orderBy: [{id: DescNullsLast}]
  ) {
    edges {
      node {
        id
      }
    }
  }
}
```

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 4
          }
        },
        {
          "node": {
            "id": 3
          }
        },
        {
          "node": {
            "id": 2
          }
        },
        {
          "node": {
            "id": 1
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Example Query Result

Source: https://supabase.github.io/pg_graphql/api/

The JSON response for the example query, showing the nested employee and email address data.

```json
{
  "data": {
    "employeeCollection": {
      "edges": [
        {
          "node": {
            "name": "Foo Barington",
            "emailAddress": {
              "address": "foo@bar.com",
              "employee": {
                "name": "Foo Barington"
              }
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Primary key query example and response

Source: https://supabase.github.io/pg_graphql/api/

Example query that retrieves a blog by id 1 and the corresponding response with the blog's fields.

```graphql
{
  blogByPk(
    id: 1
  ) {
    id
    name
    description
  }
}
```

```json
{
  "data": {
    "blogByPk": {
      "id": 1,
      "name": "Some Blog",
      "description": "Description of Some Blog"
    }
  }
}
```

--------------------------------

### Setup for partial introspection across schemas

Source: https://supabase.github.io/pg_graphql/configuration/

SQL setup with two schemas, one with introspection enabled and one disabled.

```sql
-- public schema exists by default
create schema private;

comment on schema public  is e'@graphql({"inflect_names": true, "introspection": true})';
comment on schema private is e'@graphql({"inflect_names": true, "introspection": false})';

create table public.blog(id serial primary key, content text not null);
create table private.account(id serial primary key, email text not null);

set search_path = public, private;
```

--------------------------------

### Composite primary key query example and response

Source: https://supabase.github.io/pg_graphql/api/

Example query that retrieves an item by both itemId and productId, and the corresponding response.

```graphql
{
  itemByPk(
    itemId: 1, productId: 2
  ) {
    itemId
    productId
    quantity
    price
  }
}
```

```json
{
  "data": {
    "itemByPk": {
      "itemId": 1,
      "productId": 2,
      "quantity": 1,
      "price": "24.99"
    }
  }
}
```

--------------------------------

### SQL setup for accountsByIds function

Source: https://supabase.github.io/pg_graphql/functions/

SQL to create the Account table, insert sample data, and define the accountsByIds function that accepts an array of ids.

```sql
create table "Account"(
  id serial primary key,
  email varchar(255) not null
);

insert into "Account"(email)
values
  ('a@example.com'),
  ('b@example.com'),
  ('c@example.com');

create function "accountsByIds"("ids" int[])
  returns setof "Account"
  stable
  language sql
as $$ select id, email from "Account" where id = any(ids); $$;
```

--------------------------------

### SQL Setup for Blog and BlogPost (one-to-many)

Source: https://supabase.github.io/pg_graphql/api/

Creates the Blog and BlogPost tables with a foreign key from BlogPost to Blog, defining a one-to-many relationship.

```sql
create table "Blog"(
    id serial primary key,
    name varchar(255) not null
);

create table "BlogPost"(
    id serial primary key,
    "blogId" integer not null references "Blog"(id),
    title varchar(255) not null,
    body varchar(10000)
);
```

--------------------------------

### GraphQL query for accountCollection

Source: https://supabase.github.io/pg_graphql/supabase/

Example GraphQL query that fetches the first account and its id. Used in the cURL example above.

```graphql
{
  accountCollection(first: 1) {
    edges {
      node {
        id
      }
    }
  }
}
```

--------------------------------

### Equivalent foreign key constraint and comment

Source: https://supabase.github.io/pg_graphql/views/

SQL example showing the equivalent foreign key constraint and comment directive that would produce the same relationship as the previous example. The constraint is added via ALTER TABLE and then a comment is set on the constraint.

```sql
alter table "EmailAddress"
  add constraint fkey_email_address_to_account
  foreign key ("accountId")
  references "Account" ("id");

comment on constraint fkey_email_address_to_account
  on "EmailAddress"
  is E'@graphql({"foreign_name": "account", "local_name": "addresses"})';
```

--------------------------------

### Create table with PascalCase name

Source: https://supabase.github.io/pg_graphql/configuration/

Example table definition with a quoted name `BlogPost` to illustrate default inflection behavior.

```sql
create table "BlogPost"(
    id int primary key,
    ...
);
```

--------------------------------

### JSON example: query and response

Source: https://supabase.github.io/pg_graphql/api/

GraphQL query to fetch config field and the response showing config serialized as a string.

```GraphQL
{
  userCollection {
    edges {
      node {
        config
      }
    }
  }
}
```

```JSON
{
  "data": {
    "userCollection": {
      "edges": [
        {
          "node": {
            "config": "{\"palette\": \"dark-mode\"}"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### SQL setup for composite primary key table

Source: https://supabase.github.io/pg_graphql/api/

Creates the item table with a composite primary key on item_id and product_id.

```sql
create table item(
    item_id int,
    product_id int,
    quantity int,
    price numeric(10,2),
    primary key(item_id, product_id)
);
```

--------------------------------

### BigFloat example: query and response

Source: https://supabase.github.io/pg_graphql/api/

GraphQL query to fetch id and amount, and the response showing amount serialized as a string.

```GraphQL
{
  generalLedgerCollection {
    edges {
      node {
        id
        amount
      }
    }
  }
}
```

```JSON
{
  "data": {
    "generalLedgerCollection": {
      "edges": [
        {
          "node": {
            "id": 1,
            "amount": "22.15",
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Response to node query

Source: https://supabase.github.io/pg_graphql/api/

Example JSON response for the node query, showing the returned fields.

```json
{
  "data": {
    "node": {
      "name": "Some Blog",
      "nodeId": "WyJwdWJsaWMiLCAiYmxvZyIsIDFd",
      "description": "Description of Some Blog"
    }
  }
}
```

--------------------------------

### SQL Setup for Blog table (nodeId)

Source: https://supabase.github.io/pg_graphql/api/

Creates the Blog table with a serial primary key and a name column. This table is used to illustrate the nodeId field.

```sql
create table "Blog"(
    id serial primary key,
    name varchar(255) not null
);
```

--------------------------------

### BigInt example: query and response

Source: https://supabase.github.io/pg_graphql/api/

GraphQL query to fetch id and name, and the response showing id serialized as a string.

```GraphQL
{
  personCollection {
    edges {
      node {
        id
        name
      }
    }
  }
}
```

```JSON
{
  "data": {
    "personCollection": {
      "edges": [
        {
          "node": {
            "id": "1",
            "name": "Foo Barington",
          }
        }
      ]
    }
  }
}
```

--------------------------------

### JSON response for set-returning function

Source: https://supabase.github.io/pg_graphql/functions/

Example response from a set-returning function query, showing the structure with edges and node.

```json
{
  "data": {
    "accountsByEmail": {
      "edges": [
        {
          "node": {
            "id": 1,
            "email": "a@example.com"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Upgrade pg_graphql extension with drop and create

Source: https://supabase.github.io/pg_graphql/supabase/

Drop the current pg_graphql extension and create it again to install the default version. This upgrade method has zero downtime.

```sql
drop extension pg_graphql;   -- drop version 1.1.0
create extension pg_graphql; -- install default version 1.2.0
```

--------------------------------

### SQL Setup for One-to-One Relationship

Source: https://supabase.github.io/pg_graphql/api/

Creates the EmailAddress and Employee tables. The Employee table has a unique foreign key email_address_id referencing EmailAddress(id), which defines the one-to-one relationship.

```sql
create table "EmailAddress"(
    id serial primary key,
    address text unique not null
);

create table "Employee"(
    id serial primary key,
    name text not null,
    email_address_id int unique references "EmailAddress"(id)
);
```

--------------------------------

### Keyset pagination query page 1

Source: https://supabase.github.io/pg_graphql/api/

Query to retrieve the first page of a collection using first and after arguments. The after argument is null to get the first page.

```graphql
{
  blogCollection(
    first: 2,
    after: null
  ) {
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    edges {
      cursor
      node {
        id
      }
    }
  }
}
```

--------------------------------

### Relay environment setup with Supabase

Source: https://supabase.github.io/pg_graphql/usage_with_relay/

Create a Relay environment that fetches from a Supabase GraphQL endpoint. getDataID is essential for correct cache storage, and missingFieldHandlers helps with rendering partially cached data.

```typescript
import {
  Environment,
  FetchFunction,
  Network,
  RecordSource,
  Store,
} from 'relay-runtime'

import supabase, { SUPABASE_ANON_KEY, SUPABASE_URL } from './supabase'

const fetchQuery: FetchFunction = async (operation, variables) => {
  const {
    data: { session },
  } = await supabase.auth.getSession()

  const response = await fetch(`${SUPABASE_URL}/graphql/v1`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      apikey: SUPABASE_ANON_KEY,
      Authorization: `Bearer ${session?.access_token ?? SUPABASE_ANON_KEY}`,
    },
    body: JSON.stringify({
      query: operation.text,
      variables,
    }),
  })

  return await response.json()
}

const network = Network.create(fetchQuery)
const store = new Store(new RecordSource())

const environment = new Environment({
  network,
  store,
  getDataID: (node) => node.nodeId,
  missingFieldHandlers: [
    {
      handle(field, _record, argValues) {
        if (field.name === 'node' && 'nodeId' in argValues) {
          // If field is node(nodeId: $nodeId), look up the record by the value of $nodeId
          return argValues.nodeId
        }

        return undefined
      },
      kind: 'linked',
    },
  ],
})

export default environment
```

--------------------------------

### Example Query with Pagination

Source: https://supabase.github.io/pg_graphql/usage_with_apollo/

React component using Apollo's useQuery and fetchMore to paginate through todos. The query is defined with the generated graphql function and uses a cursor for pagination.

```TypeScript
import { useQuery } from '@apollo/client'
import { graphql } from './gql'

const allTodosQueryDocument = graphql(/* GraphQL */ `
  query AllTodos($cursor: Cursor) {
    todosCollection(first: 10, after: $cursor) {
      edges {
        node {
          nodeId
          title
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
`)

const TodoList = () => {
  const { data, fetchMore } = useQuery(allTodosQueryDocument)

  return (
    <>
      {data?.thingsCollection?.edges.map(({ node }) => (
        <Todo key={node.nodeId} title={node.title} />
      ))}
      {data?.thingsCollection?.pageInfo.hasNextPage && (
        <Button
          onClick={() => {
            fetchMore({
              variables: {
                cursor: data?.thingsCollection?.pageInfo.endCursor,
              },
            })
          }}
        >
          Load More
        </Button>
      )}
    </>
  )
}

export default TodoList
```

--------------------------------

### addAccount (Mutation)

Source: https://supabase.github.io/pg_graphql/functions/

A function marked volatile is exposed on the Mutation type. This example inserts a new account and returns its ID.

```APIDOC
## addAccount

### Description
A function marked `volatile` is exposed on the Mutation type. This example inserts a new account and returns its ID.

### GraphQL Field
`addAccount(email: String!): Int`

### Arguments
- **email** (String!) - Required - Email address of the new account.

### Return Type
`Int`

### Example Mutation
```graphql
mutation {
  addAccount(email: "email@example.com")
}
```

### Example Response
```json
{
  "data": {
    "addAccount": 1
  }
}
```
```

--------------------------------

### Query node interface with inline fragment

Source: https://supabase.github.io/pg_graphql/api/

Example query using the node interface with an inline fragment to select fields for the Blog type.

```graphql
{
  node(
    nodeId: "WyJwdWJsaWMiLCAiYmxvZyIsIDFd"
  ) {
    nodeId
    # Inline fragment for `Blog` type
    ... on Blog {
      name
      description
    }
  }
}
```

--------------------------------

### Check pg_graphql version with pg_available_extensions

Source: https://supabase.github.io/pg_graphql/supabase/

Query pg_available_extensions to see the installed and default (highest available) versions of pg_graphql. The default_version is the highest version available, and installed_version is the currently enabled version.

```sql
select * from pg_available_extensions where name = 'pg_graphql'
```

--------------------------------

### Example Query for One-to-One Relationship

Source: https://supabase.github.io/pg_graphql/api/

A GraphQL query that fetches employees with their email address and the employee associated with that email address, demonstrating the bidirectional one-to-one relationship.

```graphql
{
  employeeCollection {
    edges {
      node {
        name
        emailAddress {
          address
          employee {
            name
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example SQL schema for pg_graphql

Source: https://supabase.github.io/pg_graphql/

This SQL schema defines tables `account`, `blog`, and `blog_post` with relationships and an enum type. It is used to illustrate how pg_graphql translates SQL schema into a GraphQL schema.

```sql
create table account(
    id serial primary key,
    email varchar(255) not null,
    created_at timestamp not null,
    updated_at timestamp not null
);

create table blog(
    id serial primary key,
    owner_id integer not null references account(id),
    name varchar(255) not null,
    description varchar(255),
    created_at timestamp not null,
    updated_at timestamp not null
);

create type blog_post_status as enum ('PENDING', 'RELEASED');

create table blog_post(
    id uuid not null default uuid_generate_v4() primary key,
    blog_id integer not null references blog(id),
    title varchar(255) not null,
    body varchar(10000),
    status blog_post_status not null,
    created_at timestamp not null,
    updated_at timestamp not null
);
```

--------------------------------

### Run all tests with ./bin/installcheck

Source: https://supabase.github.io/pg_graphql/contributing/

Runs all tests in the ./test/sql folder, comparing actual output in ./results with expected output in ./test/expected.

```bash
./bin/installcheck
```

--------------------------------

### Usage example: create extension, table, insert, and query

Source: https://supabase.github.io/pg_graphql/sql_interface/

Shows a complete workflow: creating the pg_graphql extension, creating a sample table, inserting a record, and querying it via GraphQL using graphql.resolve. The output displays the JSONB result with the queried data.

```sql
-- Create the extension
graphqldb= create extension pg_graphql;
CREATE EXTENSION

-- Create an example table
graphqldb= create table book(id int primary key, title text);
CREATE TABLE

-- Insert a record
graphqldb= insert into book(id, title) values (1, 'book 1');
INSERT 0 1

-- Query the table via GraphQL
graphqldb= select graphql.resolve($$
query {
  bookCollection {
    edges {
      node {
        id
      }
    }
  }
}
$$);

             resolve
----------------------------------------------------------------------
{"data": {"bookCollection": {"edges": [{"node": {"id": 1}}]}}, "errors": []}
```

--------------------------------

### Create extension and table in psql

Source: https://supabase.github.io/pg_graphql/contributing/

Commands to create the pg_graphql extension and a sample book table, with expected output shown.

```sql
graphqldb= create extension pg_graphql cascade;
CREATE EXTENSION

graphqldb= create table book(id int primary key, title text);
CREATE TABLE

graphqldb= insert into book(id, title) values (1, 'book 1');
INSERT 0 1
```

--------------------------------

### Run a single test with ./bin/installcheck aliases

Source: https://supabase.github.io/pg_graphql/contributing/

Runs the test in ./test/sql/aliases.sql by passing its name to the installcheck command.

```bash
./bin/installcheck aliases
```

--------------------------------

### Non-introspection Query Example

Source: https://supabase.github.io/pg_graphql/configuration/

Example GraphQL query and its JSON response showing that non-introspection queries continue to work when introspection is disabled.

```graphql
{
  accountCollection {
    edges {
      node {
        id
        email
      }
    }
  }
}
```

```json
{
  "data": {
    "accountCollection": {
      "edges": [
        { "node": { "id": 1, "email": "alice@example.com" } }
      ]
    }
  }
}
```

--------------------------------

### Extending Types with Functions Example

Source: https://supabase.github.io/pg_graphql/computed_fields/

Creates a function 'public._full_name' that extends the account type with a computed field 'fullName'. The function accepts a single argument of the table's tuple type. The example includes a GraphQL query that uses the computed field and a parent relationship, with the JSON response.

```sql
begin;
    comment on schema public is '@graphql({"inflect_names": true})';
    create table public.account(
        id serial primary key,
        first_name varchar(255) not null,
        last_name varchar(255) not null,
        parent_id int references account(id)
    );
    -- Extend with function
    create function public._full_name(rec public.account)
        returns text
        immutable
        strict
        language sql
    as $$
        select format('%s %s', rec.first_name, rec.last_name)
    $$;
    insert into public.account(first_name, last_name, parent_id)
    values
        ('Foo', 'Fooington', 1);
    select jsonb_pretty(
        graphql.resolve($$
    {
      accountCollection {
        edges {
          node {
            id
            firstName
            lastName
            fullName
            parent {
              fullName
            }
          }
        }
      }
    }
        $$)
    );
                      jsonb_pretty                       
---------------------------------------------------------
 {                                                      +
     "data": {                                          +
         "accountCollection": {                         +
             "edges": [                                 +
                 {                                      +
                     "node": {                          +
                         "id": 1,                       +
                         "parent": {                    +
                             "fullName": "Foo Fooington"+
                         },                             +
                         "fullName": "Foo Fooington",   +
                         "lastName": "Fooington",       +
                         "firstName": "Foo"             +
                     }                                  +
                 }                                      +
             ]                                          +
         }                                              +
     }                                                  +
 }
(1 row)

rollback;
```

--------------------------------

### GraphQL query for accountsByIds

Source: https://supabase.github.io/pg_graphql/functions/

Example query to call the accountsByIds function with an array of ids.

```graphql
query {
  accountsByIds(ids: [1, 2]) {
    edges {
      node {
        id
        email
      }
    }
  }
}
```

--------------------------------

### Filter: empty

Source: https://supabase.github.io/pg_graphql/api/

Empty filters are ignored, i.e., they behave as if the operator was not specified at all. This example shows that `and: []`, `or: []`, and `not: {}` have no effect.

```APIDOC
## GraphQL Query: blogCollection with empty filters

### Description
Empty filter objects or arrays are ignored, returning all records.

### Operation
`blogCollection`

### Arguments
- **filter** (FilterInput) - Optional - A filter object with empty `and`, `or`, and `not` keys.

### Request Example
```graphql
{
  blogCollection(
    filter: {
      and: [], or: [], not: {}
    }
  ) {
    edges {
      cursor
      node {
        id
        name
        description
        createdAt
      }
    }
  }
}
```

### Response Example
```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1,
            "name": "A: Blog 1",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc1"
          },
          "cursor": "WzFd"
        },
        {
          "node": {
            "id": 2,
            "name": "A: Blog 2",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc2"
          },
          "cursor": "WzJd"
        },
        {
          "node": {
            "id": 3,
            "name": "A: Blog 3",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc3"
          },
          "cursor": "WzNd"
        },
        {
          "node": {
            "id": 4,
            "name": "B: Blog 3",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "b desc1"
          },
          "cursor": "WzRd"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Filter: nested composition

Source: https://supabase.github.io/pg_graphql/api/

The `and`, `or`, and `not` operators can be arbitrarily nested inside each other. This example shows a complex filter combining `or` and `and` with `not`.

```APIDOC
## GraphQL Query: blogCollection with nested filter composition

### Description
Use nested `and`, `or`, and `not` operators to build complex filter logic.

### Operation
`blogCollection`

### Arguments
- **filter** (FilterInput) - Optional - A filter object with nested `and`, `or`, and `not` keys.

### Request Example
```graphql
{
  blogCollection(
    filter: {
      or: [
        { id: { eq: 1 } }
        { id: { eq: 2 } }
        { and: [{ id: { eq: 3 }, not: { name: { eq: "A: Blog 2" } } }] }
      ]
    }
  ) {
    edges {
      cursor
      node {
        id
        name
        description
        createdAt
      }
    }
  }
}
```

### Response Example
```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1,
            "name": "A: Blog 1",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc1"
          },
          "cursor": "WzFd"
        },
        {
          "node": {
            "id": 2,
            "name": "A: Blog 2",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc2"
          },
          "cursor": "WzJd"
        },
        {
          "node": {
            "id": 3,
            "name": "A: Blog 3",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc3"
          },
          "cursor": "WzNd"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Aggregate query response

Source: https://supabase.github.io/pg_graphql/api/

JSON response for the aggregate query example, showing the computed aggregate values.

```json
{
  "data": {
    "blogCollection": {
      "aggregate": {
        "count": 5,
        "sum": {
          "rating": 23,
          "visits": 1250
        },
        "avg": {
          "rating": 4.6
        },
        "min": {
          "createdAt": "2022-01-15T08:30:00Z",
          "title": "A Blog Post"
        },
        "max": {
          "rating": 5,
          "updatedAt": "2023-04-22T14:15:30Z"
        }
      }
    }
  }
}
```

--------------------------------

### GraphQL query for addNums with only a

Source: https://supabase.github.io/pg_graphql/functions/

Example query that omits argument b, relying on its default null, and provides a as 42.

```graphql
query {
  addNums(a: 42)
}
```

--------------------------------

### Delete mutation example and response

Source: https://supabase.github.io/pg_graphql/api/

Deletes the blog record with id 1 and returns the affected count and deleted records.

```graphql
mutation {
  deleteFromBlogCollection(
    filter: {id: {eq: 1}}
  ) {
    affectedCount
    records {
      id
      name
    }
  }
}
```

```json
{
  "data": {
    "deleteFromBlogCollection": {
      "records": [
        {
          "id": 1,
          "name": "baz"
        }
      ],
      "affectedCount": 1
    }
  }
}
```

--------------------------------

### contains filter with scalar query and result

Source: https://supabase.github.io/pg_graphql/api/

Example of using the 'contains' filter with a single scalar value on an array column.

```graphql
{
  blogCollection(
    filter: {tags: {contains: "tech"}},
  ) {
    edges {
      cursor
      node {
        id
        name
        tags
        createdAt
      }
    }
  }
}
```

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1,
            "name": "A: Blog 1",
            "createdAt": "2023-07-24T04:01:09.882781",
            "tags": ["tech", "innovation"]
          },
          "cursor": "WzFd"
        },
        {
          "node": {
            "id": 2,
            "name": "A: Blog 2",
            "createdAt": "2023-07-24T04:01:09.882781",
            "tags": ["tech", "innovation", "entrepreneurship"]
          },
          "cursor": "WzJd"
        }
      ]
    }
  }
}
```

--------------------------------

### Create tables and define relationship via comment directive

Source: https://supabase.github.io/pg_graphql/views/

SQL example creating Account and EmailAddress tables (without a foreign key) and adding a comment directive on EmailAddress to define a relationship to Account. The comment directive specifies local_name 'addresses' and foreign_name 'account'.

```sql
create table "Account"(
  id serial primary key,
  name text not null
);

create table "EmailAddress"(
  id serial primary key,
  "accountId" int not null, -- note: no foreign key
  "isPrimary" bool not null,
  address text not null
);

comment on table "EmailAddress" is e'
    @graphql({
        "foreign_keys": [
          {
            "local_name": "addresses",
            "local_columns": ["accountId"],
            "foreign_name": "account",
            "foreign_schema": "public",
            "foreign_table": "Account",
            "foreign_columns": ["id"]
          }
        ]
    })';
```

--------------------------------

### GraphQL query for to-many computed relationship

Source: https://supabase.github.io/pg_graphql/computed_fields/

Example query to fetch a person's addresses using the computed relationship.

```graphql
{
  personCollection {
    edges {
      node {
        id
        name
        addresses {
          edges {
            node {
              id
              address
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Create addAccount function and table (SQL)

Source: https://supabase.github.io/pg_graphql/functions/

Creates an account table and a volatile SQL function that inserts a new account and returns its id. Volatile functions are exposed on the mutation type.

```sql
create table account(
  id serial primary key,
  email varchar(255) not null
);

create function "addAccount"(email text)
  returns int
  volatile
  language sql
as $$ insert into account (email) values (email) returning id; $$;
```

--------------------------------

### addNums (Query)

Source: https://supabase.github.io/pg_graphql/functions/

A function marked immutable is exposed on the Query type. This example shows a function that adds two integers.

```APIDOC
## addNums

### Description
A function marked `immutable` is exposed on the Query type. This example adds two integers.

### GraphQL Field
`addNums(a: Int!, b: Int!): Int`

### Arguments
- **a** (Int!) - Required - First number to add.
- **b** (Int!) - Required - Second number to add.

### Return Type
`Int`

### Example Query
```graphql
query {
  addNums(a: 2, b: 3)
}
```

### Example Response
```json
{
  "data": {
    "addNums": 5
  }
}
```
```

--------------------------------

### Connect to PostgreSQL 17 with pgrx

Source: https://supabase.github.io/pg_graphql/installation/

Connects to the running PostgreSQL 17 instance using pgrx.

```bash
cargo pgrx connect pg17
```

--------------------------------

### Primary key query for non-existent id and response

Source: https://supabase.github.io/pg_graphql/api/

Example query for a non-existent id (999) and the response showing null data.

```graphql
{
  blogByPk(
    id: 999
  ) {
    id
    name
    description
  }
}
```

```json
{
  "data": {
    "blogByPk": null
  }
}
```

--------------------------------

### Filtering Result: blogCollection edges with cursor

Source: https://supabase.github.io/pg_graphql/api/

Example response from a filtered blogCollection query, showing edges with node fields and cursors.

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 2,
            "name": "A: Blog 2",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc2"
          },
          "cursor": "WzJd"
        },
        {
          "node": {
            "id": 3,
            "name": "A: Blog 3",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "a desc3"
          },
          "cursor": "WzNd"
        },
        {
          "node": {
            "id": 4,
            "name": "B: Blog 3",
            "createdAt": "2023-07-24T04:01:09.882781",
            "description": "b desc1"
          },
          "cursor": "WzRd"
        }
      ]
    }
  }
}
```

--------------------------------

### Configure Apollo Client with Supabase

Source: https://supabase.github.io/pg_graphql/usage_with_apollo/

Apollo Client setup with Supabase for authentication and pagination. Includes custom cache configuration for nodeId, relay-style pagination for todosCollection, and an auth link that adds the Supabase token and anon key to headers.

```TypeScript
import {
  ApolloClient,
  InMemoryCache,
  createHttpLink,
  defaultDataIdFromObject
} from '@apollo/client'
import { setContext } from '@apollo/client/link/context'
import { relayStylePagination } from '@apollo/client/utilities'
import supabase, { SUPABASE_ANON_KEY } from './supabase'

const cache = new InMemoryCache({
  dataIdFromObject(responseObject) {
    if ('nodeId' in responseObject) {
      return `${responseObject.nodeId}`
    }

    return defaultDataIdFromObject(responseObject)
  },
  possibleTypes: { Node: ['Todos'] }, // optional, but useful to specify supertype-subtype relationships
  typePolicies: {
    Query: {
      fields: {
        todosCollection: relayStylePagination(), // example of paginating a collection
        node: {
          read(_, { args, toReference }) {
            const ref = toReference({
              nodeId: args?.nodeId,
            })

            return ref
          },
        },
      },
    },
  },
})

const httpLink = createHttpLink({
  uri: 'http://localhost:54321/graphql/v1',
})

const authLink = setContext(async (_, { headers }) => {
  const token = (await supabase.auth.getSession()).data.session?.access_token

  return {
    headers: {
      ...headers,
      Authorization: token ? `Bearer ${token}` : '',
      apikey: SUPABASE_ANON_KEY,
    },
  }
})

const apolloClient = new ApolloClient({
  link: authLink.concat(httpLink),
  cache,
})

export default apolloClient
```

--------------------------------

### Simple filter query and result

Source: https://supabase.github.io/pg_graphql/api/

Example of a simple filter query using the 'lt' operator on the id field, and its corresponding result.

```graphql
{
  blogCollection(
    filter: {id: {lt: 3}},
  ) {
    edges {
      cursor
      node {
        id
      }
    }
  }
}
```

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1
          },
          "cursor": "WzFd"
        },
        {
          "node": {
            "id": 2
          },
          "cursor": "WzJd"
        }
      ]
    }
  }
}
```

--------------------------------

### SQL: Create tables and to-one computed relationship function

Source: https://supabase.github.io/pg_graphql/computed_fields/

Defines Person and Address tables, then creates a function 'primaryAddress' that returns setof Address with rows 1 to establish a to-one computed relationship. Includes sample inserts.

```sql
create table "Person" (
    id int primary key,
    name text
);

create table "Address"(
    id int primary key,
    "isPrimary" bool not null default false,
    "personId" int references "Person"(id),
    address text
);

-- Example computed relation
create function "primaryAddress"("Person")
    returns setof "Address" rows 1
    language sql
    as
$$
    select addr
    from "Address" addr
    where $1.id = addr."personId"
          and addr."isPrimary"
    limit 1
$$;

insert into "Person"(id, name)
values (1, 'Foo Barington');

insert into "Address"(id, "isPrimary", "personId", address)
values (4, true, 1, '1 Main St.');
```

--------------------------------

### GraphQL query for to-one computed relationship

Source: https://supabase.github.io/pg_graphql/computed_fields/

Example query to fetch a person's primary address using the computed relationship.

```graphql
{
  personCollection {
    edges {
      node {
        id
        name
        primaryAddress {
          address
        }
      }
    }

  }
}
```

--------------------------------

### Keyset pagination response page 1

Source: https://supabase.github.io/pg_graphql/api/

JSON response for the first page query, showing edges with cursors and pageInfo with hasNextPage true.

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1
          },
          "cursor": "WzFd"
        },
        {
          "node": {
            "id": 2
          },
          "cursor": "WzJd"
        }
      ],
      "pageInfo": {
        "startCursor": "WzFd",
        "endCursor": "WzJd",
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}
```
Tokens:
Raw