Metadata API Reference: Computed Fields

Introduction

computed field is an extra field added to a table, its value is computed via an SQL function which has the table row type as an input argument. Currenty, the Hasura GraphQL engine supports custom functions returning base types or table row types as computed fields.

Supported from

The metadata API is supported for versions v2.0.0 and above and replaces the older schema/metadata API.

pg_add_computed_field

pg_add_computed_field is used to define a computed field in a table. There cannot be an existing column or relationship or computed field with the same name.

Create a computed field called full_name on an author table, using an SQL function called author_full_name:

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

{
    "type":"pg_add_computed_field",
    "args":{
        "table":{
            "name":"author",
            "schema":"public"
        },
        "source": "default",
        "name":"full_name",
        "definition":{
            "function":{
                "name":"author_full_name",
                "schema":"public"
            },
            "table_argument":"author_row"
        }
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
name	true	ComputedFieldName	Name of the new computed field
definition	true	ComputedFieldDefinition	The computed field definition
comment	false	String	Customise the description shown in GraphQL introspection. If null or omitted then if a comment exists on the database function, it is used as the description, and if not, an autogenerated description is used instead.
source	false	SourceName	Name of the source database of the table (default: default)

pg_drop_computed_field

pg_drop_computed_field is used to drop a computed field of a table. If there are other objects dependent on this computed field, like permissions, the request will fail and report the dependencies unless cascade is set to true. If cascade is set to true, the dependent objects are also dropped.

Drop a computed field full_name from a table author:

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

{
    "type":"pg_drop_computed_field",
    "args":{
        "table":{
            "name":"author",
            "schema":"public"
        },
        "source": "default",
        "name":"full_name",
        "cascade": false
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
name	true	ComputedFieldName	Name of the computed field
cascade	false	Boolean	When set to true, all the dependent items (if any) on this computed fields are also dropped
source	false	SourceName	Name of the source database of the table (default: default)

bigquery_add_computed_field

bigquery_add_computed_field is used to define a computed field in a BigQuery table. There cannot be an existing column or relationship or computed field with the same name.

Create a computed field called fetch_articles on an author table, using an SQL function called author_fetch_articles:

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

{
    "type":"bigquery_add_computed_field",
    "args":{
        "table":{
            "name":"author",
            "dataset":"hasura"
        },
        "source": "bigquery",
        "name":"fetch_articles",
        "definition":{
            "function":{
                "name":"author_fetch_articles",
                "dataset":"hasura"
            },
            "argument_mapping": {
                "author_id_arg": "author_id"
            },
            "return_table": {
                "name": "article",
                "dataset": "hasura"
            }
        }
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
source	true	SourceName	Name of the source database of the table
name	true	ComputedFieldName	Name of the computed field
definition	true	ComputedFieldDefinition	The computed field definition
comment	false	String	Customise the description shown in GraphQL introspection. If null or omitted then if a comment exists on the database function, it is used as the description, and if not, an autogenerated description is used instead.

bigquery_drop_computed_field

bigquery_drop_computed_field is used to drop a computed field of a table in a BigQuery source. If there are other objects dependent on this computed field, like permissions, the request will fail and report the dependencies unless cascade is set to true. If cascade is set to true, the dependent objects are also dropped.

Drop a computed field fetch_articles from a table author:

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

{
    "type":"bigquery_drop_computed_field",
    "args":{
        "table":{
            "name":"author",
            "dataset":"hasura"
        },
        "source": "bigquery",
        "name":"fetch_articles",
        "cascade": false
    }
}

Args syntax

Key	Required	Schema	Description
table	true	TableName	Name of the table
source	true	SourceName	Name of the source database of the table
name	true	ComputedFieldName	Name of the computed field
cascade	false	Boolean	When set to true, all the dependent items (if any) on this computed fields are also dropped