API Reference: Common syntax definitions

TableName

String | QualifiedTable

QualifiedTable

{
    "name": String,
    "schema": String
}

SourceName

String

FunctionName

String | QualifiedFunction

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

Key Required Schema Description
connection_info true MsSQLSourceConnectionInfo Connection parameters for the source

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 The database connection URL string, or as an environment variable
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).

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

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)

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

String
  1. 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
  2. Character types

    Type Alias Description
    varchar text typical choice for storing string types
  3. 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
  4. Boolean type

    Type Alias Description
    boolean   state of true or false
  5. JSON types

    Type Alias Description
    json   Stored as plain text
    jsonb   Stored in a binary format and can be indexed

PGColumn

String

RelationshipName

String

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
custom_column_names false CustomColumnNames Customise the column fields

Custom Root Fields

Key Required Schema Description
select false String Customise the <table-name> root field
select_by_pk false String Customise the <table-name>_by_pk root field
select_aggregate false String Customise the <table-name>_aggregete root field
insert false String Customise the insert_<table-name> root field
insert_one false String Customise the insert_<table-name>_one root field
update false String Customise the update_<table-name> root field
update_by_pk false String Customise the update_<table-name>_by_pk root field
delete false String Customise the delete_<table-name> root field
delete_by_pk false String Customise the delete_<table-name>_by_pk 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 array Only 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

Note

There has to be at least one and only one of foreign_key_constraint_on and manual_configuration.

ObjRelUsingChoice

SameTable | RemoteTable

SameTable

PGColumn

RemoteTable

{
    "table"  : TableName,
    "column" : PGColumn
}

Supported from

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 from

Supported in v2.0.0-alpha.3 and above.

ArrRelUsing

Key Required Schema Description
foreign_key_constraint_on false ArrRelUsingFKeyOn The column with foreign key constraint
manual_configuration false ArrRelUsingManualMapping Manual mapping of table and columns

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

AndExp

{
    "$and" : [BoolExp],
}

OrExp

{
    "$or"  : [BoolExp],
}

NotExp

{
    "$not" : BoolExp
}

ExistsExp

{
    "$exists" : {
         "_table": TableName,
         "_where": BoolExp
    }
}

TrueExp

 {}

ColumnExp

{
    PGColumn : { Operator : Value }
}

Operator

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

{
  PGColumn: {
    Operator: {
      PGColumn | ["$", PGColumn]
    }
  }
}

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 :

  1. The same table -
{
  PGColumn: {
    Operator: {
      PGColumn
    }
  }
}
  1. The table on which the permission is being defined on -
{
  PGColumn: {
    Operator: {
      [$, PGColumn]
    }
  }
}
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.)

Note

  • All operators take a JSON representation of geometry/geography values as input value.

  • The input value for _st_d_within operator is an object:

    {
      field-name : {_st_d_within: {distance: Float, from: Value} }
    }
    

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"
}

Note

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

String

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
}

CollectionName

String

QueryName

String

CollectionQuery

{
    "name": String,
    "query": String
}

EndpointUrl

String

EndpointMethods

[String]

EndpointDefinition

{
    "query": {
      "query_name : String,
      "collection_name" : CollectionName
    }
}

CustomColumnNames

A JSONObject of Postgres column name to GraphQL name mapping

{
   "column1" : String,
   "column2" : String,
   ..
}

ActionName

String

WebhookURL

A String value which supports templating environment variables enclosed in {{ and }}.

String

Template example: https://{{ACTION_API_DOMAIN}}/create-user

HeaderFromValue

Key required Schema Description
name true String Name of the header
value true String Value of the header

HeaderFromEnv

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.

String

Example: String! for non-nullable String type and [String] for array of String types

GraphQLName

A string literal that conform to GraphQL spec.

String

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

InputArgument

Key Required Schema Description
name true text Name of the argument
type true GraphQLType Type of the argument

Note

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
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”.

Note

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 tracked
  • Argument modes: ONLY IN

InputObjectType

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

InputObjectField

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

String

OperationSpec

Key Required Schema Description
columns true EventTriggerColumns List of columns or “*” to listen to changes
payload false EventTriggerColumns List of columns or “*” to send as part of webhook payload

EventTriggerColumns

"*" | [PGColumn]

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

String

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:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "message": {
      "arguments":{
         "message_id":"$id"
       }
   }
}
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "messages": {
      "arguments": {
         "limit": 100
      },
      "field": {
        "private": {
          "arguments": {
             "id" : "$id"
          }
        }
      }
   }
}

InputArguments

{
  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)