docs/docs/api-reference/metadata-api/query-collections.mdx
Group queries using query collections.
Create/rename/drop query collections and add/drop a query to a collection using the following query types.
:::tip Supported from
The Metadata API is supported for versions v2.0.0 and above and
replaces the older schema/Metadata API.
:::
create_query_collection is used to define a collection.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_query_collection",
"args": {
"name": "my_collection",
"comment": "an optional comment",
"definition": {
"queries": [
{
"name": "query_1",
"query": "query { test { id name } }"
}
]
}
}
}
:::info Note
The queries in query collections are validated against the schema. So, adding an invalid query would result in inconsistent Metadata error. As the query collection is used in allowlists and REST endpoints, they are validated as well.
:::
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | CollectionName | Name of the query collection |
| definition | true | CollectionQuery array | List of queries |
| comment | false | text | Optional comment |
rename_query_collection is used to rename a collection
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "rename_query_collection",
"args": {
"name": "my_collection",
"new_name": "my_new_collection"
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | CollectionName | Name of the query collection to be replaced |
| new_name | true | CollectionName | New name of the query collection |
drop_query_collection is used to drop a collection
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_query_collection",
"args": {
"collection": "my_collection",
"cascade": false
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| collection | true | CollectionName | Name of the query collection |
| cascade | true | boolean | When set to true, the collection (if present) is removed from the allowlist |
add_query_to_collection is used to add a query to a given collection.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_query_to_collection",
"args": {
"collection_name": "my_collection",
"query_name": "query_2",
"query": "query {test {name}}"
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| collection_name | true | CollectionName | Name of the query collection |
| query_name | true | QueryName | Name of the query |
| query | true | text | The GraphQL query text |
drop_query_from_collection is used to remove a query from a given collection.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_query_from_collection",
"args": {
"collection_name": "my_collection",
"query_name": "query_2"
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| collection_name | true | CollectionName | Name of the query collection |
| query_name | true | QueryName | Name of the query |
add_collection_to_allowlist is used to add a collection to the allow-list. It is possible to specify a scope, defaulting to global.
If the given collection already exists in the allowlist regardless of scope, add_collection_to_allowlist is a no-op.
To change the scope, use update_scope_of_collection_in_allowlist.
If the scope is global, all roles will be able to access the queries present in the query collection:
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_collection_to_allowlist",
"args": {
"collection": "my_collection",
"scope": {
"global": true
}
}
}
If the scope is not global, only the listed roles are allowed to to access the queries:
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "add_collection_to_allowlist",
"args": {
"collection": "role_based_query_collection",
"scope": {
"global": false,
"roles": [
"user",
"editor"
]
}
}
}
If a query occurs in multiple collections, a role will be allowed to access the query if it is listed for any of the collections.
| Key | Required | Schema | Description |
|---|---|---|---|
| collection | true | CollectionName | Name of a query collection to be added to the allow-list |
| scope | false | AllowlistScope | Scope of the collection in the allowlist. (default: {global: true}) When the scope is global, the query collection's queries will be accessible to all roles. When the scope is non-global, the query collection's queries will be accessible to all of the roles listed in the scope. (non-global scope supported only in cloud/enterprise versions) |
update_scope_of_collection_in_allowlist is used to add change the
scope of a collection in the allowlist. Its effect is the same as first
dropping the collection from the allowlist using
drop_collection_from_allowlist, and then adding it with the given
scope using add_collection_to_allowlist.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "update_scope_of_collection_in_allowlist",
"args": {
"collection": "previously_global_query_collection",
"scope": {
"global": false,
"roles": [
"user",
"editor"
]
}
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| collection | true | CollectionName | Name of a query collection to be added to the allow-list |
| scope | true | AllowlistScope | Scope of the collection in the allowlist. When the scope is global, the query collection's queries will be accessible to all roles. When the scope is non-global, the query collection's queries will be accessible to all of the roles listed in the scope. (non-global scope supported only in cloud/enterprise versions) |
drop_collection_from_allowlist is used to remove a collection from the allow-list.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_collection_from_allowlist",
"args": {
"collection": "my_collection_1"
}
}
| Key | Required | Schema | Description |
|---|---|---|---|
| collection | true | CollectionName | Name of a query collection to be removed from the allow-list |