API Reference: Common syntax definitions TableName QualifiedTable { "name": String, "schema": String }
BigQueryTableName { "name": String, "dataset": String }
SourceName String
FunctionName QualifiedFunction { "name": String, "schema": String }
RoleName String
ComputedFieldName String
PGConfiguration Key Required Schema Description connection_info true PGSourceConnectionInfo Connection parameters for the source read_replicas false [PGSourceConnectionInfo ] Optional list of read replica configuration (supported only in cloud/enterprise versions)
MsSQLConfiguration BigQueryConfiguration Key Required Schema Description service_account true JSON String
| JSON
| FromEnv Service account for BigQuery database project_id true String
| FromEnv Project Id for BigQuery database datasets true [String]
| FromEnv List of BigQuery datasets
PGSourceConnectionInfo Key Required Schema Description database_url true String
| FromEnv | PGConnectionParameters The database connection URL as a string, as an environment variable, or as connection parameters. pool_settings false PGPoolSettings Connection pool settings use_prepared_statements false Boolean If set to true
the server prepares statement before executing on the source database (default: false
). For more details, refer to the Postgres docs isolation_level false read-committed
| repeatable-read
| serializable
The transaction isolation level in which the queries made to the source will be run with (default: read-committed
). ssl_configuration false PGCertSettings The client SSL certificate settings for the database (Only available in Cloud ).
MsSQLSourceConnectionInfo Key Required Schema Description connection_string true String
| FromEnv The database connection string, or as an environment variable pool_settings false MsSQLPoolSettings Connection pool settings
FromEnv Key Required Schema Description from_env true String
Name of the environment variable
PGConnectionParameters Key Required Schema Description username true String
The Postgres user to be connected password false String
The Postgres user's password database true String
The database name host true String
The name of the host to connect to port true Integer
The port number to connect with, at the server host
PGPoolSettings Key Required Schema Description max_connections false Integer
Maximum number of connections to be kept in the pool (default: 50) idle_timeout false Integer
The idle timeout (in seconds) per connection (default: 180) retries false Integer
Number of retries to perform (default: 1) pool_timeout false Integer
Maximum time to wait while acquiring a Postgres connection from the pool, in seconds (default: forever) connection_lifetime false Integer
Time from connection creation after which the connection should be destroyed and a new one created. A value of 0 indicates we should never destroy an active connection. If 0 is passed, memory from large query results may not be reclaimed. (default: 600 sec)
PGCertSettings Key Required Schema Description sslmode true String
The SSL connection mode. See the libpq ssl support docs for more details. sslrootcert true FromEnv Environment variable which stores trusted certificate authorities. sslcert true FromEnv Environment variable which stores the client certificate. sslkey true FromEnv Environment variable which stores the client private key. sslpassword false String
| FromEnv Password in the case where the sslkey is encrypted.
MsSQLPoolSettings Key Required Schema Description max_connections false Integer
Maximum number of connections to be kept in the pool (default: 50) idle_timeout false Integer
The idle timeout (in seconds) per connection (default: 180)
PGColumnType Numeric types
Type Alias Description serial
autoincrementing integer bigserial
autoincrementing bigint integer
4 bytes, typical choice for integer smallint
2 bytes bigint
8 bytes real
float4
6 decimal digits precision, inexact double precision
float8
15 decimal digits precision, inexact numeric
decimal
arbitrary precision, exact
Character types
Type Alias Description varchar
text
typical choice for storing string types
Date/Time types
Type Alias Description timestamp with time zone
timestamptz
both date and time, with time zone. Allowed values should be of ISO8601 format. E.g. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30 time with time zone
timetz
time of day only, with time zone. Allowed values should be of ISO8601 format. E.g. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30 date
date (no time of day). Allowed values are yyyy-mm-dd
Boolean type
Type Alias Description boolean
state of true or false
JSON types
Type Alias Description json
Stored as plain text jsonb
Stored in a binary format and can be indexed
PGColumn RelationshipName Table Config Key Required Schema Description custom_name false String
Customise the <table-name>
with the provided custom name value. The GraphQL nodes for the table will be generated according to the custom name. custom_root_fields false Custom Root Fields Customise the root fields column_config false ColumnConfig Customise the columns custom_column_names (deprecated) false CustomColumnNames Customise the column fields (deprecated in favour of custom_name on ColumnConfig ) comment false String
Customise the description shown in GraphQL introspection. If null or omitted then if a comment exists on the database table, it is used as the description (Postgres-only), and if not, an autogenerated description is used instead.
Custom Root Fields Key Required Schema Description select false String
| CustomRootField Customise the <table-name>
root field. Using a String
customises the field name. select_by_pk false String
| CustomRootField Customise the <table-name>_by_pk
root field. Using a String
customises the field name. select_aggregate false String
| CustomRootField Customise the <table-name>_aggregate
root field. Using a String
customises the field name. insert false String
| CustomRootField Customise the insert_<table-name>
root field. Using a String
customises the field name. insert_one false String
| CustomRootField Customise the insert_<table-name>_one
root field. Using a String
customises the field name. update false String
| CustomRootField Customise the update_<table-name>
root field. Using a String
customises the field name. update_by_pk false String
| CustomRootField Customise the update_<table-name>_by_pk
root field. Using a String
customises the field name. delete false String
| CustomRootField Customise the delete_<table-name>
root field. Using a String
customises the field name. delete_by_pk false String
| CustomRootField Customise the delete_<table-name>_by_pk
root field. Using a String
customises the field name.
CustomRootField Key Required Schema Description name false String
The custom root field name comment false String
Customise the description shown for the root field in GraphQL introspection. If null or omitted then an autogenerated description is used instead.
ColumnConfig A [JSONObject][https://tools.ietf.org/html/rfc7159] of table column name to ColumnConfigValue
.
ColumnConfigValue Configuration properties for particular column, as specified on ColumnConfig .
Key Required Schema Description custom_name false String
Customise the name of the field in the GraphQL schema comment false String
Customise the description shown for the field in GraphQL introspection. If null or omitted then an autogenerated description is used instead.
Custom Function Root Fields Key Required Schema Description function false String
Customise the <function-name>
root field function_aggregate false String
Customise the <function-name>_aggregete
root field
InsertPermission Key Required Schema Description check true BoolExp This expression has to hold true for every new row that is inserted set false ColumnPresetsExp Preset values for columns that can be sourced from session variables or static values columns false PGColumn array (or) '*'
Can insert into only these columns (or all when '*'
is specified) backend_only false Boolean When set to true
the mutation is accessible only if x-hasura-use-backend-only-permissions
session variable exists and is set to true
and request is made with x-hasura-admin-secret
set if any auth is configured
SelectPermission Key Required Schema Description columns true PGColumn array (or) '*'
Only these columns are selectable (or all when '*'
is specified) computed_fields false ComputedFieldName arrayOnly these computed fields are selectable filter true BoolExp Only the rows where this expression holds true are selectable limit false Integer
The maximum number of rows that can be returned allow_aggregations false Boolean
Toggle allowing aggregate queries
UpdatePermission Key Required Schema Description columns true PGColumn array (or) '*'
Only these columns are selectable (or all when '*'
is specified) filter true BoolExp Only the rows where this precondition holds true are updatable check false BoolExp Postcondition which must be satisfied by rows which have been updated set false ColumnPresetsExp Preset values for columns that can be sourced from session variables or static values.
DeletePermission Key Required Schema Description filter true BoolExp Only the rows where this expression holds true are deletable
ObjRelUsing Key Required Schema Description foreign_key_constraint_on false ObjRelUsingChoice The column with foreign key constraint or the remote table and column manual_configuration false ObjRelUsingManualMapping Manual mapping of table and columns
There has to be at least one and only one of foreign_key_constraint_on
and manual_configuration
.
ObjRelUsingChoice RemoteTable Supported in v2.0.0-alpha.3
and above.
ObjRelUsingManualMapping Key Required Schema Description remote_table true TableName The table to which the relationship has to be established column_mapping true Object (PGColumn : PGColumn ) Mapping of columns from current table to remote table insertion_order false InsertOrder insertion order: before or after parent (default: before)
InsertOrder Describes when should the referenced table row be inserted in relation
to the current table row in case of a nested insert. Defaults to
"before_parent".
"before_parent" | "after_parent"
Supported in v2.0.0-alpha.3
and above.
ArrRelUsing ArrRelUsingFKeyOn Key Required Schema Description table true TableName Name of the table column true PGColumn Name of the column with foreign key constraint
ArrRelUsingManualMapping Key Required Schema Description remote_table true TableName The table to which the relationship has to be established column_mapping true Object (PGColumn : PGColumn ) Mapping of columns from current table to remote table
BoolExp AndExp OrExp NotExp ExistsExp TrueExp ColumnExp Generic operators (all column types except json, jsonb) :
Operator PostgreSQL equivalent "$eq"
=
"$ne"
<>
"$gt"
>
"$lt"
<
"$gte"
>=
"$lte"
<=
"$in"
IN
"$nin"
NOT IN
(For more details, refer to the Postgres docs for comparison
operators
and list based search
operators .)
Text related operators :
Operator PostgreSQL equivalent "$like"
LIKE
"$nlike"
NOT LIKE
"$ilike"
ILIKE
"$nilike"
NOT ILIKE
"$similar"
SIMILAR TO
"$nsimilar"
NOT SIMILAR TO
$regex
~
$iregex
~*
$nregex
!~
$niregex
!~*
(For more details on text related operators, refer to the Postgres
docs .)
Operators for comparing columns (all column types except json,
jsonb):
Column Comparison Operator
Column comparison operators can be used to compare columns of the same
table or a related table. To compare a column of a table with another
column of :
The same table - The table on which the permission is being defined on - Operator PostgreSQL equivalent "$ceq"
=
"$cne"
<>
"$cgt"
>
"$clt"
<
"$cgte"
>=
"$clte"
<=
(For more details on comparison operators, refer to the Postgres
docs .)
Checking for NULL values :
Operator PostgreSQL equivalent _is_null
(takes true/false as values)IS NULL
(For more details on the IS NULL
expression, refer to the Postgres
docs .)
JSONB operators :
Operator PostgreSQL equivalent _contains
@>
_contained_in
<@
_has_key
?
_has_keys_any
?!
_has_keys_all
?&
(For more details on JSONB operators, refer to the Postgres
docs .)
PostGIS related operators on GEOMETRY columns:
Operator PostGIS equivalent _st_contains
ST_Contains(column, input)
_st_crosses
ST_Crosses(column, input)
_st_equals
ST_Equals(column, input)
_st_3d_intersects
ST_3DIntersects(column, input)
_st_intersects
ST_Intersects(column, input)
_st_overlaps
ST_Overlaps(column, input)
_st_touches
ST_Touches(column, input)
_st_within
ST_Within(column, input)
_st_d_within
ST_DWithin(column, input)
_st_3d_d_within
ST_3DDWithin(column, input)
(For more details on spatial relationship operators, refer to the
PostGIS
docs .)
Object A JSONObject
{ "k1" : v1, "k2" : v2, .. }
Empty Object An empty JSONObject
ColumnPresetsExp A JSONObject of a Postgres column
name to value mapping, where the value can be static or derived from a
session variable.
{ "column1" : colVal1, "column2" : colVal2, .. }
E.g. where id
is derived from a session variable and city
is a
static value.
{ "id" : "x-hasura-User-Id" , "city" : "San Francisco" }
If the value of any key begins with "x-hasura-" (case-insensitive ),
the value of the column specified in the key will be derived from a
session variable of the same name.
RemoteSchemaName RemoteSchemaDef {
"url" : url-string,
"url_from_env" : env-var-string,
"headers": [
{
"name": header-name-string,
"value": header-value-string,
"value_from_env": env-var-string
}
],
"forward_client_headers": boolean,
"timeout_seconds": integer,
"customization": RemoteSchemaCustomization
}
RemoteSchemaCustomization { "root_fields_namespace": String, "type_names": { "prefix": String, "suffix": String, "mapping": { String: String } }, "field_names": [ { "parent_type": String, "prefix": String, "suffix": String, "mapping": { String: String } } ] }
Key Required Schema Description root_fields_namespace
false String If provided, the fields of the remote schema will be nested under this top level field type_names
false RemoteTypeCustomization Customization of type names in the remote schema field_names
false [RemoteFieldCustomization ] Customization of field names for types in the remote schema
RemoteTypeCustomization Key Required Schema Description prefix
false String Prefix applied to type names in the remote schema suffix
false String Suffix applied to type names in the remote schema mapping
false {String: String}
Explicit mapping of type names in the remote schema Note: explicit mapping takes precedence over prefix
and suffix
.
Type name prefix and suffix will be applied to all types in the
schema except the root types (for query, mutation and subscription),
types starting with __
, standard scalar types (Int
, Float
,
String
, Boolean
, and ID
), and types with an explicit mapping. Root types, types starting with __
, and standard scalar types may
only be customized with an explicit mapping. RemoteFieldCustomization Key Required Schema Description parent_type
true String Name of the parent type (in the original remote schema) for fields to be customized prefix
false String Prefix applied to field names in parent type suffix
false String Suffix applied to field names in the parent type mapping
false {String: String}
Explicit mapping of field names in the parent type Note: explicit mapping takes precedence over prefix
and suffix
.
Fields that are part of an interface must be renamed consistently
across all object types that implement that interface. SourceCustomization { "root_fields": { "namespace": String, "prefix": String, "suffix": String }, "type_names": { "prefix": String, "suffix": String } }
RootFieldsCustomization Key Required Schema Description namespace
false String Namespace root field under which fields for this source will be nested prefix
false String Prefix to be prepended to all root fields in this source suffix
false String Suffix to be appended to all root fields in this source
SourceTypeCustomization Key Required Schema Description prefix
false String Prefix to be prepended to all type names in this source suffix
false String Suffix to be appended to all type names in this source
CollectionName QueryName CollectionQuery { "name": String, "query": String }
AllowlistScope {
"global": Boolean,
"roles" : [RoleName ]
}
Key Required Schema Description global false Boolean When set to false
a non empty array of role names is expected in the roles
key. When set to true
, the roles
key must be omitted. (default: true
) roles when global
is set to false
[RoleName ] Roles to which the a query collection's queries should be accessible. (supported only in cloud/enterprise versions)
EndpointUrl EndpointMethods EndpointDefinition { "query": { "query_name : String, "collection_name" : CollectionName } }
CustomColumnNames CustomColumnNames is deprecated in favour of using the custom_name
property on columns in ColumnConfig .
If both CustomColumnNames and ColumnConfig is used, any custom_name
properties used in
ColumnConfig will take precedence and any overlapped values in custom_column_names
will be discarded.
A JSONObject of Postgres column
name to GraphQL name mapping
{ "column1" : String, "column2" : String, .. }
ActionName WebhookURL A String value which supports templating environment variables enclosed
in {{
and }}
.
Template example: https://{{ACTION_API_DOMAIN}}/create-user
Key required Schema Description name true String Name of the header value true String Value of the header
Key required Schema Description name true String Name of the header value_from_env true String Name of the environment variable which holds the value of the header
GraphQLType A GraphQL Type
Reference
string.
Example: String!
for non-nullable String type and [String]
for array
of String types
GraphQLName A string literal that conform to GraphQL
spec .
ActionDefinition Key Required Schema Description arguments false Array of InputArgument Input arguments output_type true GraphQLType The output type of the action. Only object and list of objects are allowed. kind false [ synchronous
| asynchronous
] The kind of the mutation action (default: synchronous
). If the type of the action is query
then the kind
field should be omitted. headers false [HeaderFromValue | HeaderFromEnv ] List of defined headers to be sent to the handler forward_client_headers false boolean If set to true
the client headers are forwarded to the webhook handler (default: false
) handler true WebhookURL The action's webhook URL type false [ mutation
| query
] The type of the action (default: mutation
) timeout false Integer Number of seconds to wait for response before timing out. Default: 30 request_transform false RequestTransformation Request Transformation to be applied to this Action's request response_transform false ResponseTransformation Response Transformation to be applied to this Action's response
Key Required Schema Description name true text Name of the argument type true GraphQLType Type of the argument
The GraphQL Types
used in creating an action must be defined before
via Custom Types
ComputedFieldDefinition Key Required Schema Description function true FunctionName The SQL function table_argument false String Name of the argument which accepts a table row type. If omitted, the first argument is considered a table argument session_argument false String Name of the argument which accepts the Hasura session object as a JSON/JSONB value. If omitted, the Hasura session object is not passed to the function
Function Configuration Key Required Schema Description custom_name false String
Customise the <function-name>
with the provided custom name value. The GraphQL nodes for the function will be generated according to the custom name. custom_root_fields false Custom Function Root Fields Customise the root fields session_argument false String Function argument which accepts session info JSON exposed_as false String In which part of the schema should we expose this function? Either "mutation" or "query".
Currently, only functions which satisfy the following constraints can be
exposed over the GraphQL API (terminology from Postgres
docs ):
Function behaviour : STABLE
or IMMUTABLE
functions may only
be exposed as queries (i.e. with exposed_as: query
) VOLATILE
functions may be exposed as mutations or queries.Return type : MUST be SETOF <table-name>
OR <table_name>
where <table-name>
is already trackedArgument modes : ONLY IN
A simple JSON object to define GraphQL Input
Object
Key Required Schema Description name true GraphQLName Name of the Input object type description false String Description of the Input object type fields true Array of InputObjectField Fields of the Input object type
Key Required Schema Description name true GraphQLName Name of the Input object field description false String Description of the Input object field type true GraphQLType GraphQL ype of the input object field
ObjectType A simple JSON object to define GraphQL
Object
Key Required Schema Description name true GraphQLName Name of the Object type description false String Description of the Object type fields true Array of ObjectField Fields of the Object type relationships false Array of ObjectRelationship Relationships of the Object type to tables
ObjectField Key Required Schema Description name true GraphQLName Name of the Input object field description false String Description of the Input object field type true GraphQLType GraphQL type of the input object field
ObjectRelationship Key Required Schema Description name true RelationshipName Name of the relationship, shouldn't conflict with existing field names type true [ object
| array
] Type of the relationship remote_table true TableName The table to which relationship is defined field_mapping true Object (ObjectField name : Remote table's PGColumn ) Mapping of fields of object type to columns of remote table
ScalarType A simple JSON object to define GraphQL
Scalar
Key Required Schema Description name true GraphQLName Name of the Scalar type description false String Description of the Scalar type
EnumType A simple JSON object to define GraphQL
Enum
Key Required Schema Description name true GraphQLName Name of the Enum type description false String Description of the Enum type values true Array of EnumValue Values of the Enum type
EnumValue Key Required Schema Description value true GraphQLName Value of the Enum type description false String Description of the value is_deprecated false Boolean If set to true
, the enum value is marked as deprecated
TriggerName OperationSpec EventTriggerColumns Key required Schema Description version false "1" | "2" Sets the RequestTransformation
schema version. Version 1
uses a String
for the body
field and Version 2
takes a BodyTransform . Defaults to version 1
. Warning: You must remove any "version 2" schemas from your metadata prior to downgrading to v2.4.0
or earlier method false String Change the request method to this value. url false String Change the request URL to this value. body false BodyTransform | StringA template script for transforming the request body. content_type false String Replace the Content-Type with this value. Only "application/json" and "application/x-www-form-urlencoded" are allowed. Default: "application/json" query_params false Object (String : String) Replace the query params on the URL with this value. request_headers false TransformHeaders Request Header Transformation. template_engine false TemplateEngine Template language to be used for this transformation. Default: "Kriti"
HGE provides the following functions that can be used in the template:
not
: This function takes a boolean and returns its negation.
eg::
escapeUri
: This function takes a string and escapes it as per URI specification.
eg::
> {{ escapeUri "?foo=bar/baz" }} "%3Ffoo%3Dbar%2Fbaz"
getSessionVariable
: This function takes a string and returns the session variable of the given name. This function can throw the following errors:
Session variable {variable name} not found Session variable name should be a string eg::
> {{getSessionVariable "myVariableName"}} "myVariableValue"
Key required Schema Description add_headers false Object (HeaderKey : HeaderValue ) A map of Header Key Value pairs to be added to the request. remove_headers false Array of (HeaderKey ) Headers to be removed from the request.
BodyTransform Key required Schema Description action true remove | transform The action to perform on the request body. template false String The transformation template to be applied to the body. This is required if the action is transform . form_template false Object (String : String ) The key/value pairs to be used in a x-www-url-formencoded
body. The values can be transfomation templates.
TemplateEngine The JSON templating language to be used for this JSON transformation.
Key required Schema Description version false "1" | "2" Sets the RequestTransformation schema version. Version 1 uses a String for the body field and Version 2 takes a BodyTransform . Defaults to version 1 . body false BodyTransform | String
A template script for transforming the response body. template_engine false TemplateEngine Template language to be used for this transformation. Default: "Kriti"
RetryConf Key required Schema Description num_retries false Integer Number of times to retry delivery. Default: 0 interval_sec false Integer Number of seconds to wait between each retry. Default: 10 timeout_sec false Integer Number of seconds to wait for response before timing out. Default: 60
RemoteRelationshipName RemoteRelationshipDefinition Note: One of and only one of to_source
and to_remote_schema
must be present
ToSourceRelationshipDefinition Key required Schema Description relationship_type true "object" | "array" The type of the relationship field_mapping true Object (PGColumn : PGColumn ) Mapping of columns from current table to remote table source true SourceName Name of the source of the target table table true TableName Name of the target table
ToSchemaRelationshipDefinition Key Required Schema Description remote_schema true RemoteSchemaName Name of the remote schema to join with lhs_fields true [PGColumn | ComputedFieldName ] Column/Computed field(s) in the table that is used for joining with remote schema field. All join keys in remote_field
must appear here. remote_field true RemoteField The schema tree ending at the field in remote schema which needs to be joined with.
RemoteField { FieldName: { "arguments": InputArguments "field": RemoteField # optional } }
RemoteField
is a recursive tree structure that points to the field in
the remote schema that needs to be joined with. It is recursive because
the remote field maybe nested deeply in the remote schema.
Examples:
{ "message": { "arguments":{ "message_id":"$id" } } }
{ "messages": { "arguments": { "limit": 100 }, "field": { "private": { "arguments": { "id" : "$id" } } } } }
{ InputField : $PGColumn | Scalar }
Table columns can be referred by prefixing $
e.g $id
.
RemoteSchemaPermission Key Required Schema Description schema true GraphQL SDL GraphQL SDL defining the role based schema
UrlFromEnv Key required Schema Description from_env true String
Name of the environment variable which has the URL
RetryConfST Key required Schema Description num_retries false Integer Number of times to retry delivery. Default: 0 retry_interval_seconds false Integer Number of seconds to wait between each retry. Default: 10 timeout_seconds false Integer Number of seconds to wait for response before timing out. Default: 60 tolerance_seconds false Integer Number of seconds between scheduled time and actual delivery time that is acceptable. If the time difference is more than this, then the event is dropped. Default: 21600 (6 hours)