Functions

Using Postgres Functions with GraphQL.

Functions can be exposed by pg_graphql to allow running custom queries or mutations.

Query vs Mutation#

For example, a function to add two numbers will be available on the query type as a field:

Functions marked immutable or stable are available on the query type. Functions marked with the default volatile category are available on the mutation type:

Supported Return Types#

Built-in GraphQL scalar types Int, Float, String, Boolean and custom scalar types are supported as function arguments and return types. Function types returning a table or view are supported as well. Such functions implement the Node interface:

Since Postgres considers a row/composite type containing only null values to be null, the result can be a little surprising in this case. Instead of an object with all columns null, the top-level field is null:

Functions returning multiple rows of a table or view are exposed as collections.

Functions accepting or returning arrays of non-composite types are also supported. In the following example, the ids array is used to filter rows from the Account table:

Default Arguments#

Arguments without a default value are required in the GraphQL schema, to make them optional they should have a default value.

If there is no sensible default, and you still want to make the argument optional, consider using the default value null.

Currently, null defaults are only supported as simple expressions, as shown in the previous example.

Limitations#

The following features are not yet supported. Any function using these features is not exposed in the API:

• Functions that accept a table's tuple type
• Overloaded functions
• Functions with a nameless argument
• Functions returning void
• Variadic functions
• Functions that accept or return an array of composite type
• Functions that accept or return an enum type or an array of enum type