Skip to main content
Version: v2.x

API Reference: Common Syntax Definitions

TableName

QualifiedTable

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

BigQuery TableName

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

SourceName

String

FunctionName

QualifiedFunction

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

BigQuery FunctionName

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

LogicalModelName

String

RoleName

String

ComputedFieldName

String

PGConfiguration

KeyRequiredSchemaDescription
connection_infotruePGSourceConnectionInfoConnection parameters for the source
read_replicasfalse[PGSourceConnectionInfo]Optional list of read replica configuration (supported only in cloud/enterprise versions)
extensions_schemafalseStringName of the schema where the graphql-engine will install database extensions (default: public)
connection_templatefalsePGConnectionTemplateDB connection template (supported only in cloud/enterprise versions)
connection_setfalse[ConnectionSetElementConfig]Connection Set used for DB connection template(supported only in cloud/enterprise versions)

MsSQLConfiguration

KeyRequiredSchemaDescription
connection_infotrueMsSQLSourceConnectionInfoConnection parameters for the source
read_replicastrue[MsSQLSourceConnectionInfo]Optional list of read replica configuration (supported only in cloud/enterprise versions)

BigQueryConfiguration

KeyRequiredSchemaDescription
service_accounttrueJSON String | JSON | FromEnvService account for BigQuery database
project_idtrueString | FromEnvProject Id for BigQuery database
datasetstrue[String] | FromEnvList of BigQuery datasets
global_select_limitfalseIntegerThe maximum number of rows that can be returned, defaults to 1000

PGSourceConnectionInfo

KeyRequiredSchemaDescription
database_urltrueString | FromEnv | PGConnectionParameters | DynamicFromFileThe database connection URL as a string, from an environment variable, as connection parameters, or dynamically read from a file at connect time
pool_settingsfalsePGPoolSettingsConnection pool settings
use_prepared_statementsfalseBooleanIf set to true the server prepares statement before executing on the source database (default: false). For more details, refer to the Postgres docs
isolation_levelfalseread-committed | repeatable-read | serializableThe transaction isolation level in which the queries made to the source will be run with (default: read-committed).
ssl_configurationfalsePGCertSettingsThe 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

KeyRequiredSchemaDescription
connection_stringtrueString | FromEnvThe database connection string, or as an environment variable
pool_settingsfalseMsSQLPoolSettingsConnection pool settings
isolation_levelfalseread-uncommited | read-committed | repeatable-read | snapshot | serializableThe transaction isolation level in which the queries made to the source will be run with (default: read-committed).

FromEnv

KeyRequiredSchemaDescription
from_envtrueStringName of the environment variable

DynamicFromFile

KeyRequiredSchemaDescription
dynamic_from_filetrueStringFilepath 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

KeyRequiredSchemaDescription
usernametrueStringThe Postgres user to be connected
passwordfalseStringThe Postgres user's password
databasetrueStringThe database name
hosttrueStringThe name of the host to connect to
porttrueIntegerThe port number to connect with, at the server host

PGPoolSettings

KeyRequiredSchemaDescription
max_connectionsfalseIntegerMaximum number of connections to be kept in the pool (default: 50)
total_max_connectionsfalseIntegerMaximum 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_timeoutfalseIntegerThe idle timeout (in seconds) per connection (180 seconds for self-hosted & 30 seconds for Cloud).
retriesfalseIntegerNumber of retries to perform when failing to acquire connection (default: 1). Note that this configuration does not affect user/statement errors on PG.
pool_timeoutfalseIntegerMaximum time to wait while acquiring a Postgres connection from the pool, in seconds (default: forever)
connection_lifetimefalseIntegerTime 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

KeyRequiredSchemaDescription
sslmodetrueStringThe SSL connection mode. See the libpq ssl support docs for more details.
sslrootcertfalseFromEnvEnvironment variable which stores trusted certificate authorities.
sslcertfalseFromEnvEnvironment variable which stores the client certificate.
sslkeyfalseFromEnvEnvironment variable which stores the client private key.
sslpasswordfalseFromEnvPassword 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):

KeyRequiredSchemaDescription
max_connectionsfalseIntegerMaximum number of connections to be kept in the pool (default: 50)
total_max_connectionsfalseIntegerMaximum 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_timeoutfalseIntegerThe idle timeout (in seconds) per connection (default: 5)

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

KeyRequiredSchemaDescription
enabletrueBoolSet to false to disable the connection pool entirely

PGColumnType

String
  1. Numeric types

    TypeAliasDescription
    serialautoincrementing integer
    bigserialautoincrementing bigint
    integer4 bytes, typical choice for integer
    smallint2 bytes
    bigint8 bytes
    realfloat46 decimal digits precision, inexact
    double precisionfloat815 decimal digits precision, inexact
    numericdecimalarbitrary precision, exact
  2. Character types

    TypeAliasDescription
    varchartexttypical choice for storing string types
  3. Date/Time types

    TypeAliasDescription
    timestamp with time zonetimestamptzboth 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 zonetimetztime 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
    datedate (no time of day). Allowed values are yyyy-mm-dd
  4. Boolean type

    TypeAliasDescription
    booleanstate of true or false
  5. JSON types

    TypeAliasDescription
    jsonStored as plain text
    jsonbStored in a binary format and can be indexed

PGColumn

String

RelationshipName

String

Table Config

KeyRequiredSchemaDescription
custom_namefalseStringCustomize 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_fieldsfalseCustom Root FieldsCustomize the root fields
column_configfalseColumnConfigCustomize the columns
custom_column_names (deprecated)falseCustomColumnNamesCustomize the column fields (deprecated in favour of custom_name on ColumnConfig)
commentfalseStringCustomize 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

KeyRequiredSchemaDescription
selectfalseString | CustomRootFieldCustomize the <table-name> root field. Using a String customizes the field name.
select_by_pkfalseString | CustomRootFieldCustomize the <table-name>_by_pk root field. Using a String customizes the field name.
select_aggregatefalseString | CustomRootFieldCustomize the <table-name>_aggregate root field. Using a String customizes the field name.
select_streamfalseString | CustomRootFieldCustomize the <table-name>_stream root field. Using a String customizes the field name.
insertfalseString | CustomRootFieldCustomize the insert_<table-name> root field. Using a String customizes the field name.
insert_onefalseString | CustomRootFieldCustomize the insert_<table-name>_one root field. Using a String customizes the field name.
updatefalseString | CustomRootFieldCustomize the update_<table-name> root field. Using a String customizes the field name.
update_by_pkfalseString | CustomRootFieldCustomize the update_<table-name>_by_pk root field. Using a String customizes the field name.
deletefalseString | CustomRootFieldCustomize the delete_<table-name> root field. Using a String customizes the field name.
delete_by_pkfalseString | CustomRootFieldCustomize the delete_<table-name>_by_pk root field. Using a String customizes the field name.

CustomRootField

KeyRequiredSchemaDescription
namefalseStringThe custom root field name
commentfalseStringCustomize 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.

KeyRequiredSchemaDescription
custom_namefalseStringCustomize the name of the field in the GraphQL schema
commentfalseStringCustomize the description shown for the field in GraphQL introspection. If null or omitted then an autogenerated description is used instead.

Custom Function Root Fields

KeyRequiredSchemaDescription
functionfalseStringCustomize the <function-name> root field
function_aggregatefalseStringCustomize the <function-name>_aggregate root field

InputValidationDefinition

KeyRequiredSchemaDescription
urltrueWebhookURLThe input validations's webhook URL
headersfalse[HeaderFromValue | HeaderFromEnv ]List of defined headers to be sent to the handler
forward_client_headersfalsebooleanIf set to true the client headers are forwarded to the webhook handler (default: false)
timeoutfalseIntegerNumber of seconds to wait for response before timing out. Default: 10

InputValidation

KeyRequiredSchemaDescription
typetrueStringThe interface for input validation. (Currently only supports "http")
definitiontrueInputValidationDefinitionThe definition for the input validation

InsertPermission

KeyRequiredSchemaDescription
checktrueBoolExpThis expression has to hold true for every new row that is inserted
setfalseColumnPresetsExpPreset values for columns that can be sourced from session variables or static values
columnsfalsePGColumn array (or) '*'Can insert into only these columns (or all when '*' is specified)
backend_onlyfalseBooleanWhen 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_inputfalseInputValidationThe input validation definition for the insert mutation.

SelectPermission

KeyRequiredSchemaDescription
columnstruePGColumn array (or) '*'Only these columns are selectable (or all when '*' is specified)
computed_fieldsfalseComputedFieldName arrayOnly these computed fields are selectable
filtertrueBoolExpOnly the rows where this expression holds true are selectable
limitfalseIntegerThe maximum number of rows that can be returned
allow_aggregationsfalseBooleanToggle allowing aggregate queries
query_root_fieldsfalseQueryRootField arrayOnly given root fields will be enabled in the query root field. An empty list will mean no query root fields are enabled .
subscription_root_fieldsfalseSubscriptionRootField arrayOnly 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

KeyRequiredSchemaDescription
columnstruePGColumn array (or) '*'Only these columns are selectable (or all when '*' is specified)
filtertrueBoolExpOnly the rows where this precondition holds true are updatable
checkfalseBoolExpPostcondition which must be satisfied by rows which have been updated
setfalseColumnPresetsExpPreset values for columns that can be sourced from session variables or static values.
backend_onlyfalseBooleanWhen 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_inputfalseInputValidationThe input validation definition for the insert mutation.

DeletePermission

KeyRequiredSchemaDescription
filtertrueBoolExpOnly the rows where this expression holds true are deletable
backend_onlyfalseBooleanWhen 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_inputfalseInputValidationThe input validation definition for the insert mutation.

LogicalModelSelectPermission

KeyRequiredSchemaDescription
columnstruePGColumn array (or) '*'Only these columns are selectable (or all when '*' is specified)
filtertrueBoolExpOnly the rows where this expression holds true are selectable

ObjRelUsing

KeyRequiredSchemaDescription
foreign_key_constraint_onfalseObjRelUsingChoiceThe column with foreign key constraint or the remote table and column
manual_configurationfalseObjRelUsingManualMappingManual 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

{
  "table"  : TableName
  "column" : PGColumn
}
Supported from

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

ObjRelUsingManualMapping

KeyRequiredSchemaDescription
remote_tabletrueTableNameThe table to which the relationship has to be established
column_mappingtrueObject (PGColumn : PGColumn)Mapping of columns from current table to remote table
insertion_orderfalseInsertOrderinsertion 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

KeyRequiredSchemaDescription
foreign_key_constraint_onfalseArrRelUsingFKeyOnThe column with foreign key constraint
manual_configurationfalseArrRelUsingManualMappingManual mapping of table and columns

ArrRelUsingFKeyOn

KeyRequiredSchemaDescription
tabletrueTableNameName of the table
columntruePGColumnName of the column with foreign key constraint

ArrRelUsingManualMapping

KeyRequiredSchemaDescription
remote_tabletrueTableNameThe table to which the relationship has to be established
column_mappingtrueObject (PGColumn : PGColumn)Mapping of columns from current table to remote table

ScheduledEventStatus

scheduled | locked | delivered | error | dead

BoolExp

AndExp

{
  "$and" : [BoolExp]
}

OrExp

{
  "$or" : [BoolExp]
}

NotExp

{
  "$not" : BoolExp
}

ExistsExp

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

TrueExp

{}

ColumnExp

Operator

Generic operators (all column types except json, jsonb) :

OperatorPostgreSQL 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 :

OperatorPostgreSQL 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]
    }
  }
}
OperatorPostgreSQL equivalent
"$ceq"=
"$cne"<>
"$cgt">
"$clt"<
"$cgte">=
"$clte"<=

(For more details on comparison operators, refer to the Postgres docs.)

Checking for NULL values :

OperatorPostgreSQL 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 :

OperatorPostgreSQL 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:

OperatorPostGIS equivalent
_st_containsST_Contains(column, input)
_st_crossesST_Crosses(column, input)
_st_equalsST_Equals(column, input)
_st_3d_intersectsST_3DIntersects(column, input)
_st_intersectsST_Intersects(column, input)
_st_overlapsST_Overlaps(column, input)
_st_touchesST_Touches(column, input)
_st_withinST_Within(column, input)
_st_d_withinST_DWithin(column, input)
_st_3d_d_withinST_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

Subscription root field

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
}
}
]
}
KeyRequiredSchemaDescription
root_fields_namespacefalseStringIf provided, the fields of the Remote Schema will be nested under this top level field
type_namesfalseRemoteTypeCustomizationCustomization of type names in the Remote Schema
field_namesfalse[RemoteFieldCustomization]Customization of field names for types in the Remote Schema

RemoteTypeCustomization

KeyRequiredSchemaDescription
prefixfalseStringPrefix applied to type names in the Remote Schema
suffixfalseStringSuffix applied to type names in the Remote Schema
mappingfalse{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

KeyRequiredSchemaDescription
parent_typetrueStringName of the parent type (in the original Remote Schema) for fields to be customized
prefixfalseStringPrefix applied to field names in parent type
suffixfalseStringSuffix applied to field names in the parent type
mappingfalse{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
}
KeyRequiredSchemaDescription
root_fieldsfalseRootFieldsCustomizationCustomization of root field names for a source
type_namesfalseSourceTypeCustomizationCustomization of type names for a source
naming_conventionfalseStringNaming 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 ConventionField namesType namesArgumentsEnum values
hasura-defaultSnake caseSnake caseSnake caseas defined
graphql-defaultCamel casePascal caseCamel caseUppercased

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

RootFieldsCustomization

KeyRequiredSchemaDescription
namespacefalseStringNamespace root field under which fields for this source will be nested
prefixfalseStringPrefix to be prepended to all root fields in this source
suffixfalseStringSuffix to be appended to all root fields in this source

SourceTypeCustomization

KeyRequiredSchemaDescription
prefixfalseStringPrefix to be prepended to all type names in this source
suffixfalseStringSuffix to be appended to all type names in this source

CollectionName

String

QueryName

String

CollectionQuery

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

AllowlistScope

{
  "global": Boolean,
  "roles" : [RoleName]
}
KeyRequiredSchemaDescription
globalfalseBooleanWhen 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)
roleswhen 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

KeyrequiredSchemaDescription
nametrueStringName of the header
valuetrueStringValue of the header

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

Template example: header-{{HEADER_FROM_ENV}}

HeaderFromEnv

KeyrequiredSchemaDescription
nametrueStringName of the header
value_from_envtrueStringName 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

KeyRequiredSchemaDescription
argumentsfalseArray of InputArgumentInput arguments
output_typetrueGraphQLTypeThe output type of the action. Only object and list of objects are allowed.
kindfalse[ 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.
headersfalse[HeaderFromValue | HeaderFromEnv ]List of defined headers to be sent to the handler
forward_client_headersfalsebooleanIf set to true the client headers are forwarded to the webhook handler (default: false)
ignored_client_headersfalseArray of textA 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"])
handlertrueWebhookURLThe action's webhook URL
typefalse[ mutation | query ]The type of the action (default: mutation)
timeoutfalseIntegerNumber of seconds to wait for response before timing out. Default: 30
request_transformfalseRequestTransformationRequest Transformation to be applied to this Action's request
response_transformfalseResponseTransformationResponse Transformation to be applied to this Action's response

InputArgument

KeyRequiredSchemaDescription
nametruetextName of the argument
typetrueGraphQLTypeType of the argument
Note

The GraphQL Types used in creating an action must be defined before via Custom Types

ComputedFieldDefinition

KeyRequiredSchemaDescription
functiontrueFunctionNameThe SQL function
table_argumentfalseStringName of the argument which accepts a table row type. If omitted, the first argument is considered a table argument
session_argumentfalseStringName 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

KeyRequiredSchemaDescription
functiontrueBigQuery FunctionNameThe user defined SQL function
argument_mappingtrueObject (String : String)Mapping from the argument name of the function to the column name of the table
return_tablefalseBigQuery TableNameName of the table which the function returns

LogicalModelField

KeyRequiredSchemaDescription
nametrueStringThe name of the Logical Model field
typetrueLogical Model TypeA Logical Model field type
descriptionfalseStringAn extended description of the field

LogicalModelType

A Logical Model type is one of either:

A scalar:

KeyRequiredSchemaDescription
scalartrueStringThe type of the exposed column, according to the underlying data source
nullablefalseBooleanTrue if the field should be exposed over the GraphQL API as a nullable field (default: false)

An array:

KeyRequiredSchemaDescription
arraytrueLogical Model TypeA Logical Model type, which this denotes an array of
nullablefalseBooleanTrue if the field should be exposed over the GraphQL API as a nullable field (default: false)

A reference to another logical model:

KeyRequiredSchemaDescription
logical_modeltrueLogical Model TypeA Logical Model type, which this refers to. Recursive and mutually recursive references are permitted.
nullablefalseBooleanTrue if the field should be exposed over the GraphQL API as a nullable field (default: false)

NativeQueryArgument

KeyRequiredSchemaDescription
typetrueStringThe type of the column, according to the underlying data source
nullablefalseBooleanTrue if the underlying column is nullable (default: false)
descriptionfalseStringAn extended description of the argument

NativeQueryRelationship

KeyRequiredSchemaDescription
remote_native_querytrueStringThe Native Query to which the relationship has to be established
column_mappingtrueObject (local-column : remote-column)Mapping of columns from current table to remote table

Stored Procedure Argument

KeyRequiredSchemaDescription
typetrueStringThe type of the column, according to the underlying data source
nullablefalseBooleanTrue if the underlying column is nullable (default: false)
descriptionfalseStringAn extended description of the argument

Stored Procedure Configuration

KeyRequiredSchemaDescription
custom_namefalseStringCustomize 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_astrueStringIn which part of the schema should we expose this stored procedure? Currently only "query" is supported.

Function Configuration

KeyRequiredSchemaDescription
custom_namefalseStringCustomize 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_fieldsfalseCustom Function Root FieldsCustomize the root fields
session_argumentfalseStringFunction argument which accepts session info JSON
exposed_asfalseStringIn 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

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Input object type
descriptionfalseStringDescription of the Input object type
fieldstrueArray of InputObjectFieldFields of the Input object type

InputObjectField

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Input object field
descriptionfalseStringDescription of the Input object field
typetrueGraphQLTypeGraphQL ype of the input object field

ObjectType

A simple JSON object to define GraphQL Object

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Object type
descriptionfalseStringDescription of the Object type
fieldstrueArray of ObjectFieldFields of the Object type
relationshipsfalseArray of ObjectRelationshipRelationships of the Object type to tables

ObjectField

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Input object field
descriptionfalseStringDescription of the Input object field
typetrueGraphQLTypeGraphQL type of the input object field

ObjectRelationship

KeyRequiredSchemaDescription
nametrueRelationshipNameName of the relationship, shouldn't conflict with existing field names
typetrue[ object | array ]Type of the relationship
remote_tabletrueTableNameThe table to which relationship is defined
field_mappingtrueObject (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

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Scalar type
descriptionfalseStringDescription of the Scalar type

EnumType

A simple JSON object to define GraphQL Enum

KeyRequiredSchemaDescription
nametrueGraphQLNameName of the Enum type
descriptionfalseStringDescription of the Enum type
valuestrueArray of EnumValueValues of the Enum type

EnumValue

KeyRequiredSchemaDescription
valuetrueGraphQLNameValue of the Enum type
descriptionfalseStringDescription of the value
is_deprecatedfalseBooleanIf set to true, the enum value is marked as deprecated

TriggerName

String

OperationSpec

KeyRequiredSchemaDescription
columnstrueEventTriggerColumnsList of columns or "*" to listen to changes
payloadfalseEventTriggerColumnsList of columns or "*" to send as part of webhook payload

EventTriggerColumns

"*" | [PGColumn]

RequestTransformation

KeyrequiredSchemaDescription
versionfalse"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.
methodfalseStringChange the request method to this value.
urlfalseStringChange the request URL to this value.
bodyfalseBodyTransform | StringA template script for transforming the request body.
content_typefalseStringReplace the Content-Type with this value. Default: "application/json" (valid only for version 1)
query_paramsfalseObject (String : String) | StringReplace 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_headersfalseTransformHeadersRequest Header Transformation.
template_enginefalseTemplateEngineTemplate 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

KeyrequiredSchemaDescription
add_headersfalseObject (HeaderKey : HeaderValue)A map of Header Key Value pairs to be added to the request.
remove_headersfalseArray of (HeaderKey)Headers to be removed from the request.

HeaderKey

String

HeaderValue

String

BodyTransform

KeyrequiredSchemaDescription
actiontrueremove | transform | x_www_form_urlencodedThe action to perform on the request body.
templatefalseStringThe transformation template to be applied to the body. This is required if the action is transform.
form_templatefalseObject (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

KeyrequiredSchemaDescription
versionfalse"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.
bodyfalseBodyTransform | StringA template script for transforming the response body.
template_enginefalseTemplateEngineTemplate language to be used for this transformation. Default: "Kriti"

RetryConf

KeyrequiredSchemaDescription
num_retriesfalseIntegerNumber of times to retry delivery. Default: 0
interval_secfalseIntegerNumber of seconds to wait between each retry. Default: 10
timeout_secfalseIntegerNumber of seconds to wait for response before timing out. Default: 60

RemoteRelationshipName

String

RemoteRelationshipDefinition

KeyrequiredSchemaDescription
to_sourcefalseToSourceRelationshipDefinitionRemote Relationship definition to a table on a different database
to_remote_schemafalseToSchemaRelationshipDefinitionRemote Relationship definition to a Remote Schema
Note

Note: One of and only one of to_source and to_remote_schema must be present

ToSourceRelationshipDefinition

KeyrequiredSchemaDescription
relationship_typetrue"object" | "array"The type of the relationship
field_mappingtrueObject (PGColumn : PGColumn)Mapping of columns from current table to remote table
sourcetrueSourceNameName of the source of the target table
tabletrueTableNameName of the target table

ToSchemaRelationshipDefinition

KeyRequiredSchemaDescription
remote_schematrueRemoteSchemaNameName of the Remote Schema to join with
lhs_fieldstrue[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_fieldtrueRemoteFieldThe 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

KeyRequiredSchemaDescription
schematrueGraphQL SDLGraphQL SDL defining the role based schema

UrlFromEnv

KeyrequiredSchemaDescription
from_envtrueStringName of the environment variable which has the URL

RetryConfST

KeyrequiredSchemaDescription
num_retriesfalseIntegerNumber of times to retry delivery. Default: 0
retry_interval_secondsfalseIntegerNumber of seconds to wait between each retry. Default: 10
timeout_secondsfalseIntegerNumber of seconds to wait for response before timing out. Default: 60
tolerance_secondsfalseIntegerNumber 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

KeyrequiredSchemaDescription
enabletrueStringApollo federation version (can be "v1" only)

AutoEventTriggerCleanupConfig

KeyrequiredSchemaDescription
scheduletrueCron ExpressionCron expression at which the cleanup should be invoked.
clear_older_thantrueIntegerEvent logs retention period (in hours). 168 hours of retention period means that the logs older than 7 days will be removed.
batch_sizefalseIntegerMaximum 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
timeoutfalseIntegerMaximum 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_logsfalseBoolShould corresponding invocation logs be cleaned. Default false
pausedfalseBoolIs the auto-cleanup process paused. Default false

TriggerLogCleanupSources

KeyrequiredSchemaDescription
sourcestrue'*' | [SourceName]Sources for which to update the cleaner status (or all sources when '*' is provided)

EventTriggerQualifier

KeyrequiredSchemaDescription
event_triggerstrue[TriggerName]List of trigger names
source_nametrueSourceNameSource to which the Event Triggers belong

APILimitOption

KeyrequiredSchemaDescription
globaltrueIntegerMandatory limit to be set at the global level
per_rolefalseObject (String: Integer)Map of role name to limit value. This defines limits for each role

RateLimitOption

KeyrequiredSchemaDescription
globaltrueRateLimitPerRoleOptionMandatory rate limit to be set at the global level
per_rolefalseObject (String: RateLimitPerRoleOption)Map of role name to rate limit config. This defines limits for each role

RateLimitPerRoleOption

KeyrequiredSchemaDescription
unique_paramsfalseString | [String]This would be either fixed value IP or a list of Session variables
max_reqs_per_mintrueIntegerMaximum requests per minute to be allowed

PGConnectionTemplate

KeyrequiredSchemaDescription
templatetrueStringTemplate for the dynamic DB connection
versionfalseIntVersion of the template (Possible value is 1, default: 1)

ConnectionSetElementConfig

KeyrequiredSchemaDescription
nametrueStringname of the connection
connection_infotruePGSourceConnectionInfoConnection parameters for the source

RequestContext

KeyrequiredSchemaDescription
headersfalseObject (HeaderKey : HeaderValue)Request header
sessionfalseObject (String : String)Request session variables
queryfalseQueryContextOperation details

QueryContext

KeyrequiredSchemaDescription
operation_typetruequerymutationsubscriptionType of the graphql operation
operation_namefalseStringName of the graphql operation

Attribute

KeyrequiredSchemaDescription
nametrueStringName of the attribute
valuetrueStringValue of the attribute

OTLPExporter

KeyrequiredSchemaDescription
otlp_traces_endpointtrueStringOpenTelemetry compliant receiver endpoint URL for traces (usually having path "/v1/traces")
otlp_metrics_endpointtrueStringOpenTelemetry compliant receiver endpoint URL for metrics (usually having path "/v1/metrics")
otlp_logs_endpointtrueStringOpenTelemetry compliant receiver endpoint URL for logs (usually having path "/v1/logs")
protocolfalseStringProtocol to be used for the communication with the receiver. Currently only supports http/protobuf
headersfalse[HeaderFromValue | HeaderFromEnv ]List of defined headers to be sent to the receiver
resource_attributesfalse[Attribute]List of resource attributes to be sent to the receiver
traces_propagatorsfalse["tracecontext"]List of trace propagations to exchange context between services and processes

OpenTelemetryBatchSpanProcessor

KeyrequiredSchemaDescription
max_export_batch_sizefalseIntegerMaximum number of spans or logs allowed per export request. Default value is 512