Version: v2.x

API Reference: Common Syntax Definitions

TableName

String | QualifiedTable

QualifiedTable

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

BigQuery TableName

{
    "name": String,
    "dataset": String
}

SourceName

String

FunctionName

String | QualifiedFunction

QualifiedFunction

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

BigQuery FunctionName

{
    "name": String,
    "dataset": String
}

LogicalModelName

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)
extensions_schema	false	String	Name of the schema where the graphql-engine will install database extensions (default: `public`)
connection_template	false	PGConnectionTemplate	DB connection template (supported only in cloud/enterprise versions)
connection_set	false	[ConnectionSetElementConfig]	Connection Set used for DB connection template(supported only in cloud/enterprise versions)

MsSQLConfiguration

Key	Required	Schema	Description
connection_info	true	MsSQLSourceConnectionInfo	Connection parameters for the source
read_replicas	true	[MsSQLSourceConnectionInfo]	Optional list of read replica configuration (supported only in cloud/enterprise versions)

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
global_select_limit	false	`Integer`	The maximum number of rows that can be returned, defaults to `1000`

PGSourceConnectionInfo

Key	Required	Schema	Description
database_url	true	`String` \| FromEnv \| PGConnectionParameters \| DynamicFromFile	The database connection URL as a string, from an environment variable, as connection parameters, or dynamically read from a file at connect time
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).

Note

When use_prepared_statements is true, all SQL queries compiled from GraphQL queries will be prepared before being executed, meaning that the database server will cache queries and query plans.

This can result in an improvement in performance when serving mostly complex queries with little variation. But it's a trade-off that increases memory usage, and under other circumstances the result is not a net performance gain. And because the prepared statements cache is local to each database connection, the connection pool parameters also influence its efficiency.

The only way to reasonably know if enabling prepared statements will increase the performance of a Hasura GraphQL Engine instance is to benchmark it under a representative query load.

This option interacts with the Query Tags feature (see for details), and the two generally shouldn't be enabled at the same time.

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
isolation_level	false	`read-uncommited` \| `read-committed` \| `repeatable-read` \| `snapshot` \| `serializable`	The transaction isolation level in which the queries made to the source will be run with (default: `read-committed`).

FromEnv

Key	Required	Schema	Description
from_env	true	`String`	Name of the environment variable

DynamicFromFile

Key	Required	Schema	Description
dynamic_from_file	true	`String`	Filepath to a file containing a connection string. This is read before each connect, and when in use connection errors will force a re-read. For example, this can support environments where passwords are frequently rotated (not supported on Hasura Cloud). To use this the `HASURA_GRAPHQL_DYNAMIC_SECRETS_ALLOWED_PATH_PREFIX` variable must be set and non-empty. Hasura will validate that the path supplied in `dynamic_from_file` has the required prefix (e.g., `/path/to/your/secrets`).

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)
total_max_connections	false	`Integer`	Maximum number of total connections to be maintained across any number of Hasura Cloud instances (default: 1000). Takes precedence over `max_connections` in Cloud projects. (Only available in Hasura Cloud)
idle_timeout	false	`Integer`	The idle timeout (in seconds) per connection (180 seconds for self-hosted & 30 seconds for Cloud).
retries	false	`Integer`	Number of retries to perform when failing to acquire connection (default: 1). Note that this configuration does not affect user/statement errors on PG.
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	false	FromEnv	Environment variable which stores trusted certificate authorities.
sslcert	false	FromEnv	Environment variable which stores the client certificate.
sslkey	false	FromEnv	Environment variable which stores the client private key.
sslpassword	false	FromEnv	Password in the case where the sslkey is encrypted.

MsSQLPoolSettings

Pool settings have two disjoint cases.

This schema indicates that the source uses a connection pool (the default):

Key	Required	Schema	Description
max_connections	false	`Integer`	Maximum number of connections to be kept in the pool (default: 50)
total_max_connections	false	`Integer`	Maximum number of total connections across any number of Hasura Cloud instances (default: 50). Takes precedence over `max_connections` in Cloud projects. (Only available in Cloud)
idle_timeout	false	`Integer`	The idle timeout (in seconds) per connection (default: 5)

This schema indicates that the source does not use a connection pool:

Key	Required	Schema	Description
enable	true	`Bool`	Set to `false` to disable the connection pool entirely

PGColumnType

String

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

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

Type	Alias	Description
`boolean`		state of true or false

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`	Customize 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	Customize the root fields
column_config	false	ColumnConfig	Customize the columns
custom_column_names (deprecated)	false	CustomColumnNames	Customize the column fields (deprecated in favour of custom_name on ColumnConfig)
comment	false	`String`	Customize 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	Customize the `<table-name>` root field. Using a `String` customizes the field name.
select_by_pk	false	`String` \| CustomRootField	Customize the `<table-name>_by_pk` root field. Using a `String` customizes the field name.
select_aggregate	false	`String` \| CustomRootField	Customize the `<table-name>_aggregate` root field. Using a `String` customizes the field name.
select_stream	false	`String` \| CustomRootField	Customize the `<table-name>_stream` root field. Using a `String` customizes the field name.
insert	false	`String` \| CustomRootField	Customize the `insert_<table-name>` root field. Using a `String` customizes the field name.
insert_one	false	`String` \| CustomRootField	Customize the `insert_<table-name>_one` root field. Using a `String` customizes the field name.
update	false	`String` \| CustomRootField	Customize the `update_<table-name>` root field. Using a `String` customizes the field name.
update_by_pk	false	`String` \| CustomRootField	Customize the `update_<table-name>_by_pk` root field. Using a `String` customizes the field name.
delete	false	`String` \| CustomRootField	Customize the `delete_<table-name>` root field. Using a `String` customizes the field name.
delete_by_pk	false	`String` \| CustomRootField	Customize the `delete_<table-name>_by_pk` root field. Using a `String` customizes the field name.

CustomRootField

Key	Required	Schema	Description
name	false	`String`	The custom root field name
comment	false	`String`	Customize 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.

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

ColumnConfigValue

Configuration properties for particular column, as specified on ColumnConfig.

Key	Required	Schema	Description
custom_name	false	`String`	Customize the name of the field in the GraphQL schema
comment	false	`String`	Customize 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`	Customize the `<function-name>` root field
function_aggregate	false	`String`	Customize the `<function-name>_aggregate` root field

InputValidationDefinition

Key	Required	Schema	Description
url	true	WebhookURL	The input validations's webhook URL
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`)
timeout	false	Integer	Number of seconds to wait for response before timing out. Default: 10

InputValidation

Key	Required	Schema	Description
type	true	`String`	The interface for input validation. (Currently only supports "http")
definition	true	InputValidationDefinition	The definition for the input validation

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 the `x-hasura-use-backend-only-permissions` session variable exists and is set to `true` and the request is made with `x-hasura-admin-secret` set if any auth is configured
validate_input	false	InputValidation	The input validation definition for the insert mutation.

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
query_root_fields	false	QueryRootField array	Only given root fields will be enabled in the `query` root field. An empty list will mean no query root fields are enabled .
subscription_root_fields	false	SubscriptionRootField array	Only given root fields will be enabled in the `subscription` root field. An empty list will mean no subscription root fields are enabled.

Note

The query_root_fields and the subscription_root_fields are only available in v2.8.0 and above

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.
backend_only	false	Boolean	When set to `true` the mutation is accessible only if the `x-hasura-use-backend-only-permissions` session variable exists and is set to `true` and the request is made with `x-hasura-admin-secret` set if any auth is configured
validate_input	false	InputValidation	The input validation definition for the insert mutation.

DeletePermission

Key	Required	Schema	Description
filter	true	BoolExp	Only the rows where this expression holds true are deletable
backend_only	false	Boolean	When set to `true` the mutation is accessible only if the `x-hasura-use-backend-only-permissions` session variable exists and is set to `true` and the request is made with `x-hasura-admin-secret` set if any auth is configured
validate_input	false	InputValidation	The input validation definition for the insert mutation.

LogicalModelSelectPermission

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 expression holds true are selectable

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_parent")

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

ScheduledEventStatus

scheduled | locked | delivered | error | dead

BoolExp

AndExp | OrExp | NotExp | ExistsExp | TrueExp | ColumnExp

AndExp

{
  "$and" : [BoolExp]
}

OrExp

{
  "$or" : [BoolExp]
}

NotExp

{
  "$not" : BoolExp
}

ExistsExp

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

TrueExp

{}

ColumnExp

{
  PGColumn | scalar ComputedFieldName | RelationshipName | RemoteRelationshipName: { 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 :

The same table -

{
  PGColumn: {
    Operator: {
      PGColumn
    }
  }
}

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.

Query root field

select | select_by_pk | select_aggregate

Subscription root field

select | select_by_pk | select_aggregate | select_stream

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,
  "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
    },
  "naming_convention": String
}

Key	Required	Schema	Description
`root_fields`	false	RootFieldsCustomization	Customization of root field names for a source
`type_names`	false	SourceTypeCustomization	Customization of type names for a source
`naming_convention`	false	String	Naming conventions for a source

Note

Please note that the naming convention feature is an experimental feature for now. To use this feature, please use the --experimental-features=naming_convention flag or set the HASURA_GRAPHQL_EXPERIMENTAL_FEATURES environment variable to naming_convention.

The naming convention can either be graphql-default or hasura-default (default). The graphql-default naming convention is supported only for postgres databases right now. Typecase for each of the naming convention is mentioned below:

Naming Convention	Field names	Type names	Arguments	Enum values
hasura-default	Snake case	Snake case	Snake case	as defined
graphql-default	Camel case	Pascal case	Camel case	Uppercased

The naming convention can be overridden by custom_name in Table Config or by setting Custom Root Fields.

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

String

QueryName

String

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

String

EndpointMethods

[String]

EndpointDefinition

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

CustomColumnNames

Deprecation

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

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

The value field supports templating environment variables enclosed in {{ and }}.

Template example: header-{{HEADER_FROM_ENV}}

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`)
ignored_client_headers	false	Array of text	A set of client headers to ignore when forwarding headers to the webhook handler (default: `["Content-Length", "Content-MD5", "User-Agent", "Host", "Origin", "Referer", "Accept", "Accept-Encoding", "Accept-Language", "Accept-Datetime", "Cache-Control", "Connection", "DNT", "Content-Type"]`)
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

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

BigQuery ComputedFieldDefinition

Key	Required	Schema	Description
function	true	BigQuery FunctionName	The user defined SQL function
argument_mapping	true	Object (`String` : `String`)	Mapping from the argument name of the function to the column name of the table
return_table	false	BigQuery TableName	Name of the table which the function returns

LogicalModelField

Key	Required	Schema	Description
name	true	`String`	The name of the Logical Model field
type	true	Logical Model Type	A Logical Model field type
description	false	`String`	An extended description of the field

LogicalModelType

A Logical Model type is one of either:

A scalar:

Key	Required	Schema	Description
scalar	true	`String`	The type of the exposed column, according to the underlying data source
nullable	false	`Boolean`	True if the field should be exposed over the GraphQL API as a nullable field (default: `false`)

An array:

Key	Required	Schema	Description
array	true	Logical Model Type	A Logical Model type, which this denotes an array of
nullable	false	`Boolean`	True if the field should be exposed over the GraphQL API as a nullable field (default: `false`)

A reference to another logical model:

Key	Required	Schema	Description
logical_model	true	Logical Model Type	A Logical Model type, which this refers to. Recursive and mutually recursive references are permitted.
nullable	false	`Boolean`	True if the field should be exposed over the GraphQL API as a nullable field (default: `false`)

NativeQueryArgument

Key	Required	Schema	Description
type	true	`String`	The type of the column, according to the underlying data source
nullable	false	`Boolean`	True if the underlying column is nullable (default: `false`)
description	false	`String`	An extended description of the argument

NativeQueryRelationship

Key	Required	Schema	Description
remote_native_query	true	`String`	The Native Query to which the relationship has to be established
column_mapping	true	Object (local-column : remote-column)	Mapping of columns from current table to remote table

Stored Procedure Argument

Key	Required	Schema	Description
type	true	`String`	The type of the column, according to the underlying data source
nullable	false	`Boolean`	True if the underlying column is nullable (default: `false`)
description	false	`String`	An extended description of the argument

Stored Procedure Configuration

Key	Required	Schema	Description
custom_name	false	`String`	Customize the `<stored-procedure-name>` with the provided custom name value. The GraphQL nodes for the stored procedure will be generated according to the custom name.
exposed_as	true	`String`	In which part of the schema should we expose this stored procedure? Currently only "query" is supported.

Function Configuration

Key	Required	Schema	Description
custom_name	false	`String`	Customize 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	Customize 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".

Note

Currently, only functions which satisfy the following constraints can be exposed over the GraphQL API (terminology from Postgres docs):

Function behavior: 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]

RequestTransformation

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`.
method	false	String	Change the request method to this value.
url	false	String	Change the request URL to this value.
body	false	BodyTransform \| String	A template script for transforming the request body.
content_type	false	String	Replace the Content-Type with this value. Default: "application/json" (valid only for version 1)
query_params	false	Object (String : String) \| String	Replace the query params on the URL with this value. You can specify a dictionary of key/value pairs which is converted into a query string or directly give a query string.
request_headers	false	TransformHeaders	Request Header Transformation.
template_engine	false	TemplateEngine	Template language to be used for this transformation. Default: "Kriti"

Supported from

Version 2 is supported in v2.5.0 and above. You must remove any "version 2" schemas from your Metadata prior to downgrading to v2.4.0 or earlier

Note

HGE provides the following functions that can be used in the template:

not: This function takes a boolean and returns its negation.
eg::
```
  > {{not(true)}}
  false
```
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"
```

TransformHeaders

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.

HeaderKey

String

HeaderValue

String

BodyTransform

Key	required	Schema	Description
action	true	remove \| transform \| x_www_form_urlencoded	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.

"Kriti"

ResponseTransformation

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

String

RemoteRelationshipDefinition

Key	required	Schema	Description
to_source	false	ToSourceRelationshipDefinition	Remote Relationship definition to a table on a different database
to_remote_schema	false	ToSchemaRelationshipDefinition	Remote Relationship definition to a Remote Schema

Note

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

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)

ApolloFederationConfig

Key	required	Schema	Description
enable	true	String	Apollo federation version (can be `"v1"` only)

AutoEventTriggerCleanupConfig

Key	required	Schema	Description
schedule	true	Cron Expression	Cron expression at which the cleanup should be invoked.
clear_older_than	true	Integer	Event logs retention period (in hours). 168 hours of retention period means that the logs older than 7 days will be removed.
batch_size	false	Integer	Maximum number of logs to delete in a single statement during the cleanup action. If there are more events to be cleaned than the `batch_size` then the cleanup action will execute multiple statements sequentially until all old event logs are cleared. Default 10000
timeout	false	Integer	Maximum time (in seconds) that a batch can take during the cleanup process. If a batch times out, the cleanup process is halted. Default: 60
clean_invocation_logs	false	Bool	Should corresponding invocation logs be cleaned. Default `false`
paused	false	Bool	Is the auto-cleanup process paused. Default `false`

TriggerLogCleanupSources

Key	required	Schema	Description
sources	true	`'*'` \| [SourceName]	Sources for which to update the cleaner status (or all sources when `'*'` is provided)

EventTriggerQualifier

Key	required	Schema	Description
event_triggers	true	[TriggerName]	List of trigger names
source_name	true	SourceName	Source to which the Event Triggers belong

APILimitOption

Key	required	Schema	Description
global	true	Integer	Mandatory limit to be set at the global level
per_role	false	Object (`String`: Integer)	Map of role name to limit value. This defines limits for each role

RateLimitOption

Key	required	Schema	Description
global	true	RateLimitPerRoleOption	Mandatory rate limit to be set at the global level
per_role	false	Object (`String`: RateLimitPerRoleOption)	Map of role name to rate limit config. This defines limits for each role

RateLimitPerRoleOption

Key	required	Schema	Description
unique_params	false	`String` \| [`String`]	This would be either fixed value `IP` or a list of Session variables
max_reqs_per_min	true	Integer	Maximum requests per minute to be allowed

PGConnectionTemplate

Key	required	Schema	Description
template	true	String	Template for the dynamic DB connection
version	false	Int	Version of the template (Possible value is 1, default: 1)

ConnectionSetElementConfig

Key	required	Schema	Description
name	true	String	name of the connection
connection_info	true	PGSourceConnectionInfo	Connection parameters for the source

RequestContext

Key	required	Schema	Description
headers	false	Object (HeaderKey : HeaderValue)	Request header
session	false	Object (String : String)	Request session variables
query	false	QueryContext	Operation details

QueryContext

Key	required	Schema	Description
operation_type	true	query	mutation	subscription	Type of the graphql operation
operation_name	false	String	Name of the graphql operation

Attribute

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

OTLPExporter

Key	required	Schema	Description
otlp_traces_endpoint	true	`String`	OpenTelemetry compliant receiver endpoint URL for traces (usually having path "/v1/traces")
otlp_metrics_endpoint	true	`String`	OpenTelemetry compliant receiver endpoint URL for metrics (usually having path "/v1/metrics")
otlp_logs_endpoint	true	`String`	OpenTelemetry compliant receiver endpoint URL for logs (usually having path "/v1/logs")
protocol	false	`String`	Protocol to be used for the communication with the receiver. Currently only supports `http/protobuf`
headers	false	[HeaderFromValue \| HeaderFromEnv ]	List of defined headers to be sent to the receiver
resource_attributes	false	[Attribute]	List of resource attributes to be sent to the receiver
traces_propagators	false	["tracecontext"]	List of trace propagations to exchange context between services and processes

OpenTelemetryBatchSpanProcessor

Key	required	Schema	Description
max_export_batch_size	false	`Integer`	Maximum number of spans or logs allowed per export request. Default value is 512

API Reference: Common Syntax Definitions

TableName​

QualifiedTable​

BigQuery TableName​

SourceName​

FunctionName​

QualifiedFunction​

BigQuery FunctionName​

LogicalModelName​

RoleName​

ComputedFieldName​

PGConfiguration​

MsSQLConfiguration​

BigQueryConfiguration​

PGSourceConnectionInfo​

MsSQLSourceConnectionInfo​

FromEnv​

DynamicFromFile​

PGConnectionParameters​

PGPoolSettings​

PGCertSettings​

MsSQLPoolSettings​

PGColumnType​

PGColumn​

RelationshipName​

Table Config​

Custom Root Fields​

CustomRootField​

ColumnConfig​

ColumnConfigValue​

Custom Function Root Fields​

InputValidationDefinition​

InputValidation​

InsertPermission​

SelectPermission​

UpdatePermission​

DeletePermission​

LogicalModelSelectPermission​

ObjRelUsing​

ObjRelUsingChoice​

SameTable​

RemoteTable​

ObjRelUsingManualMapping​

InsertOrder​

ArrRelUsing​

ArrRelUsingFKeyOn​

ArrRelUsingManualMapping​

ScheduledEventStatus​

BoolExp​

AndExp​

OrExp​

NotExp​

ExistsExp​

TrueExp​

ColumnExp​

Operator​

Object​

Empty Object​

ColumnPresetsExp​

Query root field​

Subscription root field​

RemoteSchemaName​

RemoteSchemaDef​

RemoteSchemaCustomization​

RemoteTypeCustomization​

RemoteFieldCustomization​

SourceCustomization​

RootFieldsCustomization​

SourceTypeCustomization​

CollectionName​

QueryName​

CollectionQuery​

AllowlistScope​

EndpointUrl​

EndpointMethods​

EndpointDefinition​

CustomColumnNames​

ActionName​

WebhookURL​

HeaderFromValue​

TableName

QualifiedTable

BigQuery TableName

SourceName

FunctionName

QualifiedFunction

BigQuery FunctionName

LogicalModelName

RoleName

ComputedFieldName

PGConfiguration

MsSQLConfiguration

BigQueryConfiguration

PGSourceConnectionInfo

MsSQLSourceConnectionInfo

FromEnv

DynamicFromFile

PGConnectionParameters

PGPoolSettings

PGCertSettings

MsSQLPoolSettings

PGColumnType

PGColumn

RelationshipName

Table Config

Custom Root Fields

CustomRootField

ColumnConfig

ColumnConfigValue

Custom Function Root Fields

InputValidationDefinition

InputValidation

InsertPermission

SelectPermission

UpdatePermission

DeletePermission

LogicalModelSelectPermission

ObjRelUsing

ObjRelUsingChoice

SameTable

RemoteTable

ObjRelUsingManualMapping

InsertOrder

ArrRelUsing

ArrRelUsingFKeyOn

ArrRelUsingManualMapping

ScheduledEventStatus

BoolExp

AndExp

OrExp

NotExp

ExistsExp

TrueExp

ColumnExp

Operator

Object

Empty Object

ColumnPresetsExp

Query root field

Subscription root field

RemoteSchemaName

RemoteSchemaDef

RemoteSchemaCustomization

RemoteTypeCustomization

RemoteFieldCustomization

SourceCustomization

RootFieldsCustomization

SourceTypeCustomization

CollectionName

QueryName

CollectionQuery

AllowlistScope

EndpointUrl

EndpointMethods

EndpointDefinition

CustomColumnNames

ActionName

WebhookURL

HeaderFromValue

HeaderFromEnv