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
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
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). |
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
Numeric types
Type | Alias | Description |
---|
serial | | autoincrementing integer |
bigserial | | autoincrementing bigint |
integer | | 4 bytes, typical choice for integer |
smallint | | 2 bytes |
bigint | | 8 bytes |
real | float4 | 6 decimal digits precision, inexact |
double precision | float8 | 15 decimal digits precision, inexact |
numeric | decimal | arbitrary precision, exact |
Character types
Type | Alias | Description |
---|
varchar | text | typical choice for storing string types |
Date/Time types
Type | Alias | Description |
---|
timestamp with time zone | timestamptz | both date and time, with time zone. Allowed values should be of ISO8601 format. E.g. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30 |
time with time zone | timetz | time of day only, with time zone. Allowed values should be of ISO8601 format. E.g. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30 |
date | | date (no time of day). Allowed values are yyyy-mm-dd |
Boolean type
Type | Alias | Description |
---|
boolean | | state of true or false |
JSON types
Type | Alias | Description |
---|
json | | Stored as plain text |
jsonb | | Stored in a binary format and can be indexed |
PGColumn
RelationshipName
Table Config
Key | Required | Schema | Description |
---|
custom_name | false | String | 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
.
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 |
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 |
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. |
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 |
There has to be at least one and only one of foreign_key_constraint_on
and manual_configuration
.
ObjRelUsingChoice
RemoteTable
Supported in v2.0.0-alpha.3
and above.
ObjRelUsingManualMapping
Key | Required | Schema | Description |
---|
remote_table | true | TableName | The table to which the relationship has to be established |
column_mapping | true | Object (PGColumn : PGColumn) | Mapping of columns from current table to remote table |
insertion_order | false | InsertOrder | insertion order: before or after parent (default: "before_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 in v2.0.0-alpha.3
and above.
ArrRelUsing
ArrRelUsingFKeyOn
Key | Required | Schema | Description |
---|
table | true | TableName | Name of the table |
column | true | PGColumn | Name of the column with foreign key constraint |
ArrRelUsingManualMapping
Key | Required | Schema | Description |
---|
remote_table | true | TableName | The table to which the relationship has to be established |
column_mapping | true | Object (PGColumn : PGColumn) | Mapping of columns from current table to remote table |
ScheduledEventStatus
scheduled | locked | delivered | error | dead
BoolExp
AndExp
OrExp
NotExp
ExistsExp
TrueExp
ColumnExp
Generic operators (all column types except json, jsonb) :
Operator | PostgreSQL equivalent |
---|
"$eq" | = |
"$ne" | <> |
"$gt" | > |
"$lt" | < |
"$gte" | >= |
"$lte" | <= |
"$in" | IN |
"$nin" | NOT IN |
(For more details, refer to the Postgres docs for
comparison operators and
list based search operators.)
Text related operators :
Operator | PostgreSQL equivalent |
---|
"$like" | LIKE |
"$nlike" | NOT LIKE |
"$ilike" | ILIKE |
"$nilike" | NOT ILIKE |
"$similar" | SIMILAR TO |
"$nsimilar" | NOT SIMILAR TO |
$regex | ~ |
$iregex | ~* |
$nregex | !~ |
$niregex | !~* |
(For more details on text related operators, refer to the
Postgres docs.)
Operators for comparing columns (all column types except json, jsonb):
Column Comparison Operator
Column comparison operators can be used to compare columns of the same table or a related table. To compare a column of
a table with another column of :
- The same table -
- The table on which the permission is being defined on -
Operator | PostgreSQL equivalent |
---|
"$ceq" | = |
"$cne" | <> |
"$cgt" | > |
"$clt" | < |
"$cgte" | >= |
"$clte" | <= |
(For more details on comparison operators, refer to the
Postgres docs.)
Checking for NULL values :
Operator | PostgreSQL equivalent |
---|
_is_null (takes true/false as values) | IS NULL |
(For more details on the IS NULL
expression, refer to the
Postgres docs.)
JSONB operators :
Operator | PostgreSQL equivalent |
---|
_contains | @> |
_contained_in | <@ |
_has_key | ? |
_has_keys_any | ?! |
_has_keys_all | ?& |
(For more details on JSONB operators, refer to the
Postgres docs.)
PostGIS related operators on GEOMETRY columns:
Operator | PostGIS equivalent |
---|
_st_contains | ST_Contains(column, input) |
_st_crosses | ST_Crosses(column, input) |
_st_equals | ST_Equals(column, input) |
_st_3d_intersects | ST_3DIntersects(column, input) |
_st_intersects | ST_Intersects(column, input) |
_st_overlaps | ST_Overlaps(column, input) |
_st_touches | ST_Touches(column, input) |
_st_within | ST_Within(column, input) |
_st_d_within | ST_DWithin(column, input) |
_st_3d_d_within | ST_3DDWithin(column, input) |
(For more details on spatial relationship operators, refer to the
PostGIS docs.)
Object
A JSONObject
{
"k1" : v1,
"k2" : v2,
..
}
Empty Object
An empty JSONObject
ColumnPresetsExp
A JSONObject of a Postgres column name to value mapping, where the value can be
static or derived from a session variable.
{
"column1" : colVal1,
"column2" : colVal2,
..
}
E.g. where id
is derived from a session variable and city
is a static value.
{
"id": "x-hasura-User-Id",
"city": "San Francisco"
}
If the value of any key begins with "x-hasura-" (case-insensitive), the value of the column specified in the key will
be derived from a session variable of the same name.
Query root field
Subscription root field
RemoteSchemaName
RemoteSchemaDef
{
"url" : url-string,
"url_from_env" : env-var-string,
"headers": [
{
"name": header-name-string,
"value": header-value-string,
"value_from_env": env-var-string
}
],
"forward_client_headers": boolean,
"timeout_seconds": integer,
"customization": RemoteSchemaCustomization
}
RemoteSchemaCustomization
{
"root_fields_namespace": String,
"type_names": {
"prefix": String,
"suffix": String,
"mapping": {
String: String
}
},
"field_names": [
{
"parent_type": String,
"prefix": String,
"suffix": String,
"mapping": {
String: String
}
}
]
}
Key | Required | Schema | Description |
---|
root_fields_namespace | false | String | If provided, the fields of the Remote Schema will be nested under this top level field |
type_names | false | RemoteTypeCustomization | Customization of type names in the Remote Schema |
field_names | false | [RemoteFieldCustomization] | Customization of field names for types in the Remote Schema |
RemoteTypeCustomization
Key | Required | Schema | Description |
---|
prefix | false | String | Prefix applied to type names in the Remote Schema |
suffix | false | String | Suffix applied to type names in the Remote Schema |
mapping | false | {String: String} | Explicit mapping of type names in the Remote Schema Note: explicit mapping takes precedence over prefix and suffix . |
- Type name prefix and suffix will be applied to all types in the schema except the root types (for query, mutation and
subscription), types starting with
__
, standard scalar types (Int
, Float
, String
, Boolean
, and ID
), and
types with an explicit mapping. - Root types, types starting with
__
, and standard scalar types may only be customized with an explicit mapping.
RemoteFieldCustomization
Key | Required | Schema | Description |
---|
parent_type | true | String | Name of the parent type (in the original Remote Schema) for fields to be customized |
prefix | false | String | Prefix applied to field names in parent type |
suffix | false | String | Suffix applied to field names in the parent type |
mapping | false | {String: String} | Explicit mapping of field names in the parent type Note: explicit mapping takes precedence over prefix and suffix . |
- Fields that are part of an interface must be renamed consistently across all object types that implement that
interface.
SourceCustomization
{
"root_fields": {
"namespace": String,
"prefix": String,
"suffix": String
},
"type_names": {
"prefix": String,
"suffix": String
},
"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 |
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
QueryName
CollectionQuery
{
"name": String,
"query": String
}
AllowlistScope
{
"global": Boolean,
"roles" : [RoleName]
}
Key | Required | Schema | Description |
---|
global | false | Boolean | When set to false a non empty array of role names is expected in the roles key. When set to true , the roles key must be omitted. (default: true ) |
roles | when global is set to false | [RoleName] | Roles to which the a query collection's queries should be accessible. (supported only in cloud/enterprise versions) |
EndpointUrl
EndpointMethods
EndpointDefinition
{
"query": {
"query_name : String, "collection_name" : CollectionName
}
}
CustomColumnNames
CustomColumnNames is deprecated in favour of using the custom_name
property on columns in
ColumnConfig. If both CustomColumnNames and ColumnConfig is used, any custom_name
properties used in ColumnConfig will take precedence and any overlapped values in custom_column_names
will be discarded.
A JSONObject of Postgres column name to GraphQL name mapping
{
"column1" : String,
"column2" : String,
..
}
ActionName
WebhookURL
A String value which supports templating environment variables enclosed in {{
and }}
.
Template example: https://{{ACTION_API_DOMAIN}}/create-user
Key | required | Schema | Description |
---|
name | true | String | Name of the header |
value | true | String | Value of the header |
The value
field supports templating environment variables enclosed in {{
and }}
.
Template example: header-{{HEADER_FROM_ENV}}
Key | required | Schema | Description |
---|
name | true | String | Name of the header |
value_from_env | true | String | Name of the environment variable which holds the value of the header |
GraphQLType
A GraphQL Type Reference string.
Example: String!
for non-nullable String type and [String]
for array of String types
GraphQLName
A string literal that conform to GraphQL spec.
ActionDefinition
Key | Required | Schema | Description |
---|
arguments | false | Array of InputArgument | Input arguments |
output_type | true | GraphQLType | The output type of the action. Only object and list of objects are allowed. |
kind | false | [ synchronous | asynchronous ] | The kind of the mutation action (default: synchronous ). If the type of the action is query then the kind field should be omitted. |
headers | false | [HeaderFromValue | HeaderFromEnv ] | List of defined headers to be sent to the handler |
forward_client_headers | false | boolean | If set to true the client headers are forwarded to the webhook handler (default: false ) |
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 |
Key | Required | Schema | Description |
---|
name | true | text | Name of the argument |
type | true | GraphQLType | Type of the argument |
The GraphQL Types
used in creating an action must be defined before via
Custom Types
ComputedFieldDefinition
Key | Required | Schema | Description |
---|
function | true | FunctionName | The SQL function |
table_argument | false | String | Name of the argument which accepts a table row type. If omitted, the first argument is considered a table argument |
session_argument | false | String | Name of the argument which accepts the Hasura session object as a JSON/JSONB value. If omitted, the Hasura session object is not passed to the function |
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". |
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
A simple JSON object to define GraphQL Input Object
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Input object type |
description | false | String | Description of the Input object type |
fields | true | Array of InputObjectField | Fields of the Input object type |
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Input object field |
description | false | String | Description of the Input object field |
type | true | GraphQLType | GraphQL ype of the input object field |
ObjectType
A simple JSON object to define GraphQL Object
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Object type |
description | false | String | Description of the Object type |
fields | true | Array of ObjectField | Fields of the Object type |
relationships | false | Array of ObjectRelationship | Relationships of the Object type to tables |
ObjectField
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Input object field |
description | false | String | Description of the Input object field |
type | true | GraphQLType | GraphQL type of the input object field |
ObjectRelationship
Key | Required | Schema | Description |
---|
name | true | RelationshipName | Name of the relationship, shouldn't conflict with existing field names |
type | true | [ object | array ] | Type of the relationship |
remote_table | true | TableName | The table to which relationship is defined |
field_mapping | true | Object (ObjectField name : Remote table's PGColumn) | Mapping of fields of object type to columns of remote table |
ScalarType
A simple JSON object to define GraphQL Scalar
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Scalar type |
description | false | String | Description of the Scalar type |
EnumType
A simple JSON object to define GraphQL Enum
Key | Required | Schema | Description |
---|
name | true | GraphQLName | Name of the Enum type |
description | false | String | Description of the Enum type |
values | true | Array of EnumValue | Values of the Enum type |
EnumValue
Key | Required | Schema | Description |
---|
value | true | GraphQLName | Value of the Enum type |
description | false | String | Description of the value |
is_deprecated | false | Boolean | If set to true , the enum value is marked as deprecated |
TriggerName
OperationSpec
EventTriggerColumns
Key | required | Schema | Description |
---|
version | false | "1" | "2" | Sets the RequestTransformation schema version. Version 1 uses a String for the body field and Version 2 takes a BodyTransform. Defaults to version 1 . |
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" |
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
HGE provides the following functions that can be used in the template:
not
: This function takes a boolean and returns its negation.
eg::
escapeUri
: This function takes a string and escapes it as per URI specification.
eg::
> {{ escapeUri("?foo=bar/baz") }}
"%3Ffoo%3Dbar%2Fbaz"
getSessionVariable
: This function takes a string and returns the session variable of the given name. This function
can throw the following errors:
- Session variable {variable name} not found
- Session variable name should be a string
eg::
> {{getSessionVariable("myVariableName")}}
"myVariableValue"
Key | required | Schema | Description |
---|
add_headers | false | Object (HeaderKey : HeaderValue) | A map of Header Key Value pairs to be added to the request. |
remove_headers | false | Array of (HeaderKey) | Headers to be removed from the request. |
BodyTransform
Key | required | Schema | Description |
---|
action | true | remove | transform | 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.
Key | required | Schema | Description |
---|
version | false | "1" | "2" | Sets the RequestTransformation schema version. Version 1 uses a String for the body field and Version 2 takes a BodyTransform. Defaults to version 1. |
body | false | BodyTransform | String | A template script for transforming the response body. |
template_engine | false | TemplateEngine | Template language to be used for this transformation. Default: "Kriti" |
RetryConf
Key | required | Schema | Description |
---|
num_retries | false | Integer | Number of times to retry delivery. Default: 0 |
interval_sec | false | Integer | Number of seconds to wait between each retry. Default: 10 |
timeout_sec | false | Integer | Number of seconds to wait for response before timing out. Default: 60 |
RemoteRelationshipName
RemoteRelationshipDefinition
Note: One of and only one of to_source
and to_remote_schema
must be present
ToSourceRelationshipDefinition
Key | required | Schema | Description |
---|
relationship_type | true | "object" | "array" | The type of the relationship |
field_mapping | true | Object (PGColumn : PGColumn) | Mapping of columns from current table to remote table |
source | true | SourceName | Name of the source of the target table |
table | true | TableName | Name of the target table |
ToSchemaRelationshipDefinition
Key | Required | Schema | Description |
---|
remote_schema | true | RemoteSchemaName | Name of the Remote Schema to join with |
lhs_fields | true | [PGColumn | ComputedFieldName] | Column/Computed field(s) in the table that is used for joining with Remote Schema field. All join keys in remote_field must appear here. |
remote_field | true | RemoteField | The schema tree ending at the field in Remote Schema which needs to be joined with. |
RemoteField
{
FieldName: {
"arguments": InputArguments "field": RemoteField # optional
}
}
RemoteField
is a recursive tree structure that points to the field in the Remote Schema that needs to be joined with.
It is recursive because the remote field maybe nested deeply in the Remote Schema.
Examples:
{
"message": {
"arguments":{
"message_id":"$id"
}
}
}
{
"messages": {
"arguments": {
"limit": 100
},
"field": {
"private": {
"arguments": {
"id" : "$id"
}
}
}
}
}
{
InputField : $PGColumn | Scalar
}
Table columns can be referred by prefixing $
e.g $id
.
RemoteSchemaPermission
Key | Required | Schema | Description |
---|
schema | true | GraphQL SDL | GraphQL SDL defining the role based schema |
UrlFromEnv
Key | required | Schema | Description |
---|
from_env | true | String | Name of the environment variable which has the URL |
RetryConfST
Key | required | Schema | Description |
---|
num_retries | false | Integer | Number of times to retry delivery. Default: 0 |
retry_interval_seconds | false | Integer | Number of seconds to wait between each retry. Default: 10 |
timeout_seconds | false | Integer | Number of seconds to wait for response before timing out. Default: 60 |
tolerance_seconds | false | Integer | Number of seconds between scheduled time and actual delivery time that is acceptable. If the time difference is more than this, then the event is dropped. Default: 21600 (6 hours) |
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 |