hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-15 09:22:43 +03:00
Code Issues Projects Releases Wiki Activity

docs: Logical Model + Native Query documentation for SQL Server and BigQuery.

Browse Source 
This adds Logical Model + Native Query documentation for SQL Server and BigQuery. It is very similar to the documentation for PostgreSQL.

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9194
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
GitOrigin-RevId: 84c003ad4a836c16590c1eccccef02279937fc10
This commit is contained in:
Samir Talwar 2023-05-17 16:14:18 +02:00 committed by hasura-bot
parent 42817af958
commit 428613d3f3
12 changed files with 1805 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/docs/api-reference/metadata-api/index.mdx
View File

@ -66,7 +66,7 @@ The structure of args depends on the type and version.
The various types of queries are listed in the following table:
| `type` | `args` | `version` | Synopsis |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
| **bulk** | [Query](#metadata-query) array | 1 | Execute multiple operations in a single query |
| **concurrent_bulk** | [Query](#metadata-query) array | 2 | Execute multiple **read only** operations in a single **transaction** |
| **bulk_keep_going** | [Query](#metadata-query) array | 1 | Like `bulk`, but subcommands can fail without the whole batch failing |
@ -119,6 +119,12 @@ The various types of queries are listed in the following table:
| [bigquery_add_computed_field](/api-reference/metadata-api/computed-field.mdx#metadata-bigquery-add-computed-field) | [bigquery_add_computed_field_args](/api-reference/metadata-api/computed-field.mdx#metadata-bigquery-add-computed-field-syntax) | 1 | Add a computed field to a BigQuery table |
| [bigquery_drop_computed_field](/api-reference/metadata-api/computed-field.mdx#metadata-bigquery-drop-computed-field) | [bigquery_drop_computed_field_args](/api-reference/metadata-api/computed-field.mdx#metadata-bigquery-drop-computed-field-syntax) | 1 | Drop a BigQuery computed field |
| [bigquery_set_apollo_federation_config](/api-reference/metadata-api/table-view.mdx#metadata-bigquery-set-apollo-federation-config) | [bigquery_set_apollo_federation_config_args](/api-reference/metadata-api/table-view.mdx#metadata-bigquery-set-apollo-federation-config-syntax) | 1 | Set Apollo Federation configuration of an already tracked bigquery table |
| [bigquery_track_logical_model](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-track-logical-model) | [bigquery_track_logical_model_args](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-track-logical-model-syntax) | 1 | Add a Logical Model |
| [bigquery_untrack_logical_model](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-untrack-logical-model) | [bigquery_untrack_logical_model_args](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-untrack-logical-model-syntax) | 1 | Remove a Logical Model |
| [bigquery_create_logical_model_select_permission](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-create-logical-model-select-permission) | [bigquery_create_logical_model_select_permission_args](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-create-logical-model-select-permission-syntax) | 1 | Add select permissions for a Logical Model |
| [bigquery_drop_logical_model_select_permission](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-drop-logical-model-select-permission) | [bigquery_drop_logical_model_select_permission_args](/api-reference/metadata-api/logical-models.mdx#metadata-bigquery-drop-logical-model-select-permission-syntax) | 1 | Remove select permissions for a Logical Model |
| [bigquery_track_native_query](/api-reference/metadata-api/native-queries.mdx#metadata-bigquery-track-native-query) | [bigquery_track_native_query_args](/api-reference/metadata-api/native-queries.mdx#metadata-bigquery-track-native-query-syntax) | 1 | Add a Native Query |
| [bigquery_untrack_native_query](/api-reference/metadata-api/native-queries.mdx#metadata-bigquery-untrack-native-query) | [bigquery_untrack_native_query_args](/api-reference/metadata-api/native-queries.mdx#metadata-bigquery-untrack-native-query-syntax) | 1 | Remove a Native Query |
| [mssql_add_source](/api-reference/metadata-api/source.mdx#mssql-add-source) | [mssql_add_source_args](/api-reference/metadata-api/source.mdx#mssql-add-source-syntax) | 1 | Add an MS SQL Server database |
| [mssql_drop_source](/api-reference/metadata-api/source.mdx#mssql-drop-source) | [mssql_drop_source_args](/api-reference/metadata-api/source.mdx#mssql-drop-source-syntax) | 1 | Remove an MS SQL Server database |
| [mssql_get_source_tables](/api-reference/metadata-api/source.mdx#mssql-get-source-tables) | [mssql_get_source_tables_args](/api-reference/metadata-api/source.mdx#mssql-get-source-tables-syntax) | 1 | List all tables available on a given MS SQL Server database |
@ -142,6 +148,12 @@ The various types of queries are listed in the following table:
| [mssql_drop_delete_permission](/api-reference/metadata-api/permission.mdx#mssql-drop-delete-permission) | [mssql_drop_delete_permission_args](/api-reference/metadata-api/permission.mdx#mssql-drop-delete-permission-syntax) | 1 | Remove existing delete permission for an MS SQL Server table/view |
| [mssql_set_permission_comment](/api-reference/metadata-api/permission.mdx#mssql-set-permission-comment) | [mssql_set_permission_comment_args](/api-reference/metadata-api/permission.mdx#mssql-set-permission-comment-syntax) | 1 | Set comment on an existing permission for an MS SQL Server table/view |
| [mssql_set_apollo_federation_config](/api-reference/metadata-api/table-view.mdx#metadata-mssql-set-apollo-federation-config) | [mssql_set_apollo_federation_config_args](/api-reference/metadata-api/table-view.mdx#metadata-mssql-set-apollo-federation-config-syntax) | 1 | Set Apollo Federation configuration of an already tracked mssql table |
| [mssql_track_logical_model](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-track-logical-model) | [mssql_track_logical_model_args](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-track-logical-model-syntax) | 1 | Add a Logical Model |
| [mssql_untrack_logical_model](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-untrack-logical-model) | [mssql_untrack_logical_model_args](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-untrack-logical-model-syntax) | 1 | Remove a Logical Model |
| [mssql_create_logical_model_select_permission](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-create-logical-model-select-permission) | [mssql_create_logical_model_select_permission_args](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-create-logical-model-select-permission-syntax) | 1 | Add select permissions for a Logical Model |
| [mssql_drop_logical_model_select_permission](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-drop-logical-model-select-permission) | [mssql_drop_logical_model_select_permission_args](/api-reference/metadata-api/logical-models.mdx#metadata-mssql-drop-logical-model-select-permission-syntax) | 1 | Remove select permissions for a Logical Model |
| [mssql_track_native_query](/api-reference/metadata-api/native-queries.mdx#metadata-mssql-track-native-query) | [mssql_track_native_query_args](/api-reference/metadata-api/native-queries.mdx#metadata-mssql-track-native-query-syntax) | 1 | Add a Native Query |
| [mssql_untrack_native_query](/api-reference/metadata-api/native-queries.mdx#metadata-mssql-untrack-native-query) | [mssql_untrack_native_query_args](/api-reference/metadata-api/native-queries.mdx#metadata-mssql-untrack-native-query-syntax) | 1 | Remove a Native Query |
| [create_cron_trigger](/api-reference/metadata-api/scheduled-triggers.mdx#metadata-create-cron-trigger) | [create_cron_trigger_args](/api-reference/metadata-api/scheduled-triggers.mdx#metadata-create-cron-trigger-syntax) | 1 | Create a cron trigger |
| [delete_cron_trigger](/api-reference/metadata-api/scheduled-triggers.mdx#metadata-delete-cron-trigger) | [delete_cron_trigger_args](/api-reference/metadata-api/scheduled-triggers.mdx#metadata-delete-cron-trigger-syntax) | 1 | Delete an existing cron trigger |
| [get_cron_triggers](/api-reference/metadata-api/scheduled-triggers.mdx#metadata-get-cron-triggers) | [Empty Object](/api-reference/syntax-defs.mdx#empty-object) | 1 | Returns all the cron triggers |

259
docs/docs/api-reference/metadata-api/logical-models.mdx
View File

@ -42,7 +42,7 @@ X-Hasura-Role: admin
"fields": [
{
"name": "<field name>",
"type": "<postgres field type>",
"type": "<PostgreSQL field type>",
"nullable": false | true,
"description": "<optional field description>"
},
@ -90,7 +90,7 @@ X-Hasura-Role: admin
## pg_create_logical_model_select_permission {#metadata-pg-create-logical-model-select-permission}
`pg_create_logical_model_select_permission` is used to add permission to an existing Logical Model.
`pg_create_logical_model_select_permission` is used to add a permission to an existing Logical Model.
```http
POST /v1/metadata HTTP/1.1
@ -150,3 +150,258 @@ X-Hasura-Role: admin
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| role | true | [RoleName](/api-reference/syntax-defs.mdx#rolename) | Name of the role |
## mssql_track_logical_model {#metadata-mssql-track-logical-model}
`mssql_track_logical_model` is used to add a Logical Model to the GraphQL schema.
Track a Logical Model as follows:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<SQL Server field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
The type of each field can be any valid SQL Server data type, and each field can be marked as nullable or not.
### Args syntax {#metadata-mssql-track-logical-model-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| fields | false | Array of [LogicalModelField](/api-reference/syntax-defs.mdx#logicalmodelfield) | Configuration for each field exposed by the Logical Model GraphQL type |
## mssql_untrack_logical_model {#metadata-mssql-untrack-logical-model}
`mssql_untrack_logical_model` is used to remove a Logical Model from the GraphQL schema.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_untrack_logical_model",
"args": {
"source": "default",
"name": "<name>"
}
}
```
### Args syntax {#metadata-mssql-untrack-logical-model-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
## mssql_create_logical_model_select_permission {#metadata-mssql-create-logical-model-select-permission}
`mssql_create_logical_model_select_permission` is used to add a permission to an existing Logical Model.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>",
"permission": {
"columns": "*" | [
"column 1",
"column 2",
...
],
"filter": <boolean expression>
}
}
}
```
### Args syntax {#metadata-mssql-create-logical-model-select-permission-syntax}
| Key | Required | Schema | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| role | true | [RoleName](/api-reference/syntax-defs.mdx#rolename) | Name of the role |
| permission | true | [LogicalModelSelectPermission](/api-reference/syntax-defs.mdx#logicalmodelselectpermission) | Permission configuration |
## mssql_drop_logical_model_select_permission {#metadata-mssql-drop-logical-model-select-permission}
`mssql_drop_logical_model_select_permission` is used to drop an existing Logical Model permission.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_drop_logical_model_select_permission",
"args": {
"source": "default",
"function": "get_articles",
"role": "user"
}
}
```
### Args syntax {#metadata-mssql-drop-logical-model-select-permission-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| role | true | [RoleName](/api-reference/syntax-defs.mdx#rolename) | Name of the role |
## bigquery_track_logical_model {#metadata-bigquery-track-logical-model}
`bigquery_track_logical_model` is used to add a Logical Model to the GraphQL schema.
Track a Logical Model as follows:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<BigQuery field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
marked as nullable or not.
### Args syntax {#metadata-bigquery-track-logical-model-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| fields | false | Array of [LogicalModelField](/api-reference/syntax-defs.mdx#logicalmodelfield) | Configuration for each field exposed by the Logical Model GraphQL type |
## bigquery_untrack_logical_model {#metadata-bigquery-untrack-logical-model}
`bigquery_untrack_logical_model` is used to remove a Logical Model from the GraphQL schema.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_untrack_logical_model",
"args": {
"source": "default",
"name": "<name>"
}
}
```
### Args syntax {#metadata-bigquery-untrack-logical-model-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
## bigquery_create_logical_model_select_permission {#metadata-bigquery-create-logical-model-select-permission}
`bigquery_create_logical_model_select_permission` is used to add a permission to an existing Logical Model.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>",
"permission": {
"columns": "*" | [
"column 1",
"column 2",
...
],
"filter": <boolean expression>
}
}
}
```
### Args syntax {#metadata-bigquery-create-logical-model-select-permission-syntax}
| Key | Required | Schema | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| role | true | [RoleName](/api-reference/syntax-defs.mdx#rolename) | Name of the role |
| permission | true | [LogicalModelSelectPermission](/api-reference/syntax-defs.mdx#logicalmodelselectpermission) | Permission configuration |
## bigquery_drop_logical_model_select_permission {#metadata-bigquery-drop-logical-model-select-permission}
`bigquery_drop_logical_model_select_permission` is used to drop an existing Logical Model permission.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_drop_logical_model_select_permission",
"args": {
"source": "default",
"function": "get_articles",
"role": "user"
}
}
```
### Args syntax {#metadata-bigquery-drop-logical-model-select-permission-syntax}
| Key | Required | Schema | Description |
| ------ | -------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| name | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the Logical Model |
| role | true | [RoleName](/api-reference/syntax-defs.mdx#rolename) | Name of the role |

132
docs/docs/api-reference/metadata-api/native-queries.mdx
View File

@ -88,3 +88,135 @@ X-Hasura-Role: admin
| --------------- | -------- | ------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| root_field_name | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the Native Query |
## mssql_track_native_query {#metadata-mssql-track-native-query}
`mssql_track_native_query` is used to add a Native Query to the GraphQL schema.
Track a Native Query as follows:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_native_query",
"args": {
"source": "default",
"root_field_name": "<name>",
"type": "query",
"arguments": {
"<name>": {
"type": "<postgres field type>",
"nullable": false | true,
"description": "<optional field description>"
}
},
"code": "<SQL query>",
"returns": "<logical model name>"
}
}
```
### Args syntax {#metadata-mssql-track-native-query-syntax}
| Key | Required | Schema | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| root_field_name | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the Native Query |
| type | false | `"query"` | The type of the GraphQL query (currently must be `"query"`) |
| arguments | true | Mapping from String to [NativeQueryArgument](/api-reference/syntax-defs.mdx#nativequeryargument) | Configuration for each argument |
| code | true | String | The SQL to run on request |
| returns | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the logical model representing the resulting schema |
## mssql_untrack_native_query {#metadata-mssql-untrack-native-query}
`mssql_untrack_native_query` is used to remove a Native Query from the GraphQL schema.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_untrack_native_query",
"args": {
"source": "default",
"root_field_name": "<name>"
}
}
```
### Args syntax {#metadata-mssql-untrack-native-query-syntax}
| Key | Required | Schema | Description |
| --------------- | -------- | ------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| root_field_name | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the Native Query |
## bigquery_track_native_query {#metadata-bigquery-track-native-query}
`bigquery_track_native_query` is used to add a Native Query to the GraphQL schema.
Track a Native Query as follows:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_native_query",
"args": {
"source": "default",
"root_field_name": "<name>",
"type": "query",
"arguments": {
"<name>": {
"type": "<postgres field type>",
"nullable": false | true,
"description": "<optional field description>"
}
},
"code": "<SQL query>",
"returns": "<logical model name>"
}
}
```
### Args syntax {#metadata-bigquery-track-native-query-syntax}
| Key | Required | Schema | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| root_field_name | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the Native Query |
| type | false | `"query"` | The type of the GraphQL query (currently must be `"query"`) |
| arguments | true | Mapping from String to [NativeQueryArgument](/api-reference/syntax-defs.mdx#nativequeryargument) | Configuration for each argument |
| code | true | String | The SQL to run on request |
| returns | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the logical model representing the resulting schema |
## bigquery_untrack_native_query {#metadata-bigquery-untrack-native-query}
`bigquery_untrack_native_query` is used to remove a Native Query from the GraphQL schema.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_untrack_native_query",
"args": {
"source": "default",
"root_field_name": "<name>"
}
}
```
### Args syntax {#metadata-bigquery-untrack-native-query-syntax}
| Key | Required | Schema | Description |
| --------------- | -------- | ------------------------------------------------------- | ------------------------------------------------ |
| source | false | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database (default: `default`) |
| root_field_name | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the Native Query |

5
docs/docs/schema/bigquery/logical-models/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Extend with Logical Models",
"position": 3,
"className": "cloud-and-enterprise-icon"
}

281
docs/docs/schema/bigquery/logical-models/index.mdx Normal file
View File

@ -0,0 +1,281 @@
---
slug: index
description: Customize the Hasura GraphQL schema with Logical Models
keywords:
- hasura
- docs
- bigquery
- schema
- logical models
- native queries
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# BigQuery: Logical Models
## Introduction
:::tip Supported from
Native queries are supported from `v2.26.0`.
:::
Logical Models are a GraphQL representation of database data. They provide an abstraction over the underlying database.
Logical Models are a new approach from Hasura and are currently used by the
[Native Queries](/schema/bigquery/logical-models/native-queries.mdx) feature to automatically create a GraphQL API for a
native database query.
You can find examples of how to use logical models in the
[Native Queries](/schema/bigquery/logical-models/native-queries.mdx) documentation. For a more detailed explanation of
Logical Models themselves, read on.
## Tracking a Logical Model
:::info Only creatable via the API
Currently, Logical Models can only be created via the API. Console and CLI support will be added in a future release.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
You create a logical model through the metadata API:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<BigQuery field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
</TabItem>
</Tabs>
The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
marked as nullable or not.
For example, we could track a representation of an article as follows:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_logical_model",
"args": {
"source": "default",
"name": "article",
"fields": [
{
"name": "id",
"type": "integer"
},
{
"name": "title",
"type": "text"
},
{
"name": "contents",
"type": "text"
},
{
"name": "published_date",
"type": "published_date",
"nullable": true
},
{
"name": "is_published",
"type": "boolean"
}
]
}
}
```
</TabItem>
</Tabs>
## Untracking a Logical Model
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
You can remove a Logical Model the same way:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_untrack_logical_model",
"args": {
"source": "default",
"name": "<name>"
}
}
```
</TabItem>
</Tabs>
:::info Removing a Logical Model
Note that you can only remove an **unused** Logical Model; if the model is attached to a Native Query, this operation
will fail. You must remove the Native Query first.
:::
To untrack the above "article" Logical Model, we would run the following:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_untrack_logical_model",
"args": {
"source": "default",
"name": "article"
}
}
```
</TabItem>
</Tabs>
## Permissions
By default, a model has no permissions, and only the admin account will be able to use it. You can enable the model by
adding permissions for a given role.
As Logical Models are currently only used for read-only purposes, you can only add select permissions.
The permissions consist of a list of columns that the role can access, and a filter that specifies which rows the role
can receive.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
Columns must be specified, though you can use `"*"` to specify that you want to allow all columns.
The filter is the same boolean expression syntax as [query filters](/queries/bigquery/query-filters.mdx). To allow all
rows to be passed through to the response, you can specify an empty filter, `{}`.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>",
"permission": {
"columns": "*" | [
"column 1",
"column 2",
...
],
"filter": <boolean expression>
}
}
}
```
</TabItem>
</Tabs>
For example, to allow access to the "article" Logical Model for the "reader" role, but only for published articles, we
could use the following permission to limit the accessible rows to those where `is_published` is `true`, and then hide
that column from the list (by specifying all other columns).
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "article",
"role": "reader",
"permission": {
"columns": [
"id",
"title",
"contents",
"date"
],
"filter": {
"is_published": {"_eq": true}
}
}
}
}
```
</TabItem>
</Tabs>
You can also drop permissions:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_drop_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>"
}
}
```
</TabItem>
</Tabs>
## Relationships
Currently, Logical Models do not support relationships. They will be supported in a future release.

344
docs/docs/schema/bigquery/logical-models/native-queries.mdx Normal file
View File

@ -0,0 +1,344 @@
---
sidebar_label: Native Queries
sidebar_position: 4
description: Customize the Hasura GraphQL schema with native queries
keywords:
- hasura
- docs
- bigquery
- schema
- logical models
- native queries
sidebar_class_name: beta-tag
---
import ProductBadge from '@site/src/components/ProductBadge';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# BigQuery: Native Queries
<div className="badge-container">
<ProductBadge standard pro ee self />
<div className="badge badge-gray heading-badge">Beta</div>
</div>
## What are Native Queries?
:::tip Supported from
Native queries are supported from `v2.26.0`.
:::
The Hasura GraphQL Engine automatically generates a GraphQL API around database objects. That includes querying,
mutating, and subscribing to data changes and events. However, sometimes we need more custom or advanced behavior that
doesn’t come out of the box.
Native Queries allows you to automatically generate a GraphQL API around raw SQL queries, giving you more flexibility
and control over your Hasura-generated GraphQL schema. They allow you to harness the full power of SQL within Hasura
without the need to create database objects that require DDL privileges.
You might find Native Queries useful for many reasons:
- Use the full power of SQL that Hasura might not provide access to through the typical table API, such as `GROUP BY`,
window functions, or scalar functions.
- Provide custom arguments to the users of your API to greatly expand its flexibility.
- Encapsulate sophisticated filtering with a query, allowing your users to provide a single argument rather than having
to understand how to manipulate the data.
- Work with the advanced features of your database to improve performance.
- Write a compatibility layer around tables, making it easier to change your API without breaking existing clients.
- Reduce duplication by moving common data manipulation into one place.
Native Queries are a Cloud and Enterprise feature of Hasura.
:::info Supported features
Currently, Hasura aggregations are not supported, but you can write the aggregation yourself as part of the query.
Relationships will be supported in a future release.
:::
## Example: excerpts of articles
We’ll start with an example. Let’s use this new feature to add some custom functionality to our Hasura API, without
needing to define a custom SQL function on the database. If you’d like some reference documentation, scroll down, and
also take a look at the [Logical Models documentation](/schema/bigquery/logical-models/index.mdx).
Imagine we have some articles in a table, with content kindly donated by [Loripsum.net](https://loripsum.net/):
```sql
CREATE TABLE article(
id SERIAL NOT NULL PRIMARY KEY,
title TEXT NOT NULL,
date DATE NOT NULL,
content TEXT NOT NULL
);
INSERT INTO article(title, date, content) VALUES
('You will not believe', '2023-01-01', 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Facillimum id quidem est, inquam. Esse enim, nisi eris, non potes. Oratio me istius philosophi non offendit; Idemne, quod iucunde? Quid est enim aliud esse versutum? Non autem hoc: igitur ne illud quidem.'),
('Ten things that', '2023-02-02', 'Illi enim inter se dissentiunt. Sedulo, inquam, faciam. Simus igitur contenti his.'),
('Did you know', '2023-03-03', 'Ratio quidem vestra sic cogit. Duo Reges: constructio interrete. An nisi populari fama? Erat enim res aperta. Apparet statim, quae sint officia, quae actiones. Tum mihi Piso: Quid ergo?'),
('They just cannot', '2023-04-04', 'Itaque hic ipse iam pridem est reiectus; Quod quidem iam fit etiam in Academia. Negare non possum. Quis non odit sordidos, vanos, leves, futtiles?'),
('What on earth', '2023-05-05', 'Venit ad extremum; At certe gravius. Efficiens dici potest. Rhetorice igitur, inquam, nos mavis quam dialectice disputare? Nunc de hominis summo bono quaeritur; Rationis enim perfectio est virtus;');
```
When listing these articles in an index, we probably want to truncate the text to, let’s say, 20 characters. So let’s
create a Logical Model representing the excerpted article:
:::info Only creatable via the API
Currently, Native Queries can only be created using the API. Console and CLI support will be added in a future release.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_logical_model",
"args": {
"source": "default",
"name": "article_excerpt",
"fields": [
{
"name": "id",
"type": "integer"
},
{
"name": "title",
"type": "text"
},
{
"name": "date",
"type": "date"
},
{
"name": "excerpt",
"type": "text"
}
]
}
}
```
</TabItem>
</Tabs>
We can then track a Native Query that takes a single argument, `max_length`, and uses it to truncate the article content
(more on arguments below). We use the SQL `substring` function to truncate the function, and the `length` function to
decide whether we should use an ellipsis.
We use `{{max_length}}` to refer to the argument. We need it twice, so we simply use the argument twice.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_native_query",
"args": {
"type": "query",
"source": "default",
"root_field_name": "article_with_excerpt",
"arguments": {
"max_length": {
"type": "integer"
}
},
"returns": "article_excerpt",
"code": "SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article"
}
}
```
</TabItem>
</Tabs>
All that’s left is for us to make a GraphQL query to select some articles with excerpts using our new root field
generated in the previous API call. All we need to provide is the date range we’re interested in:
```graphql
query {
article_with_excerpt(args: { max_length: 20 }, where: { date: { _gte: "2023-03-01" } }) {
id
title
date
excerpt
}
}
```
When we run this GraphQL query, we get the following results:
```json
{
"data": {
"article_with_excerpt": [
{
"id": 3,
"title": "Did you know",
"date": "2023-03-03",
"excerpt": "Ratio quidem vestra ..."
},
{
"id": 4,
"title": "They just cannot",
"date": "2023-04-04",
"excerpt": "Itaque hic ipse iam ..."
},
{
"id": 5,
"title": "What on earth",
"date": "2023-05-05",
"excerpt": "Venit ad extremum; A..."
}
]
}
}
```
## Creating a Native Query
### 1. Create a Logical Model
In order to represent the structure of the data returned by the query, we first create a Logical Model.
:::info Permissions and Logical Models
Note that this Logical Model has no attached permissions and therefore will only be available to the admin account. See
the [Logical Model documentation](/schema/bigquery/logical-models/index.mdx) for information on attaching permissions.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<BigQuery field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
</TabItem>
</Tabs>
### 2. Create a Native Query
Once the Logical Model is defined, we can use it to define the query:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_track_native_query",
"args": {
"source": "default",
"root_field_name": "<name>",
"type": "query",
"arguments": {
"<name>": {
"type": "<BigQuery field type>",
"nullable": false | true,
"description": "<optional field description>"
}
},
"code": "<SQL query>",
"returns": "<logical model name>"
}
}
```
</TabItem>
</Tabs>
You can use any SQL that you could potentially use in a parameterized query, with the following caveats:
- The query must currently be a single read-only SQL query.
- The query must be a valid standalone query, and not a partial query.
- The return type of the query must match with the Logical Model.
- The SQL cannot invoke a stored procedure.
#### Arguments
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the
syntax `{{argument_name}}`. This syntax resembles popular string templating languages such as Mustache, but does not use
string interpolation. Instead, it works in exactly the same way as prepared statements in the database, and so arguments
do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
This does mean that arguments cannot be used for elements of the SQL that deal with structure. For example, you cannot
use an argument to specify the name of the table in a `FROM` clause.
When making a query, the arguments are specified using the `args` parameter of the query root field.
## Using the Native Query
You can make a GraphQL request using the specified root field name just as you would any other GraphQL query. When
making a query, the arguments are specified using the `args` parameter of the query root field.
```graphql
query {
<root field name>(
[args: {"<argument name>": <argument value>, ...},]
[where: ...,]
[order_by: ..., distinct_on: ...,]
[limit: ..., offset: ...]
) {
<field 1>
<field 2>
...
}
}
```
## Query functionality
Just like tables, native queries generate GraphQL types with the ability to further break down the data. You can find
more information in the relevant documentation for [filtering](/queries/bigquery/query-filters.mdx),
[sorting](/queries/bigquery/sorting.mdx), [distinct queries](/queries/bigquery/distinct-queries.mdx), and
[pagination](/queries/bigquery/pagination.mdx).
## Mutations
Currently, only read-only queries are supported. All queries are run in a read-only transaction where supported to
enforce this constraint.
A future release will allow mutations to be specified using native queries.
## Permissions
Native queries will inherit the permissions of the Logical Model that they return. See the
[documentation on Logical Models](/schema/bigquery/logical-models/index.mdx) for an explanation of how to add
permissions.

1
docs/docs/schema/ms-sql-server/index.mdx
View File

@ -25,6 +25,7 @@ MS SQL Server constructs.
- [Tables basics](/schema/ms-sql-server/tables.mdx)
- [Table relationships](/schema/ms-sql-server/table-relationships/index.mdx)
- [Extend with logical models](/schema/ms-sql-server/logical-models/index.mdx)
- [Extend with views](/schema/ms-sql-server/views.mdx)
- [Default field values](/schema/ms-sql-server/default-values/index.mdx)
- [Customize auto-generated fields](/schema/ms-sql-server/custom-field-names.mdx)

5
docs/docs/schema/ms-sql-server/logical-models/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Extend with Logical Models",
"position": 3,
"className": "cloud-and-enterprise-icon"
}

280
docs/docs/schema/ms-sql-server/logical-models/index.mdx Normal file
View File

@ -0,0 +1,280 @@
---
slug: index
description: Customize the Hasura GraphQL schema with Logical Models
keywords:
- hasura
- docs
- ms sql server
- schema
- logical models
- native queries
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# MS SQL Server: Logical Models
## Introduction
:::tip Supported from
Native queries are supported from `v2.26.0`.
:::
Logical Models are a GraphQL representation of database data. They provide an abstraction over the underlying database.
Logical Models are a new approach from Hasura and are currently used by the
[Native Queries](/schema/ms-sql-server/logical-models/native-queries.mdx) feature to automatically create a GraphQL API
for a native database query.
You can find examples of how to use logical models in the
[Native Queries](/schema/ms-sql-server/logical-models/native-queries.mdx) documentation. For a more detailed explanation
of Logical Models themselves, read on.
## Tracking a Logical Model
:::info Only creatable via the API
Currently, Logical Models can only be created via the API. Console and CLI support will be added in a future release.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
You create a logical model through the metadata API:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<SQL Server field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
</TabItem>
</Tabs>
The type of each field can be any valid SQL Server data type, and each field can be marked as nullable or not.
For example, we could track a representation of an article as follows:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_logical_model",
"args": {
"source": "default",
"name": "article",
"fields": [
{
"name": "id",
"type": "int"
},
{
"name": "title",
"type": "text"
},
{
"name": "contents",
"type": "text"
},
{
"name": "published_date",
"type": "published_date",
"nullable": true
},
{
"name": "is_published",
"type": "bit"
}
]
}
}
```
</TabItem>
</Tabs>
## Untracking a Logical Model
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
You can remove a Logical Model the same way:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_untrack_logical_model",
"args": {
"source": "default",
"name": "<name>"
}
}
```
</TabItem>
</Tabs>
:::info Removing a Logical Model
Note that you can only remove an **unused** Logical Model; if the model is attached to a Native Query, this operation
will fail. You must remove the Native Query first.
:::
To untrack the above "article" Logical Model, we would run the following:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_untrack_logical_model",
"args": {
"source": "default",
"name": "article"
}
}
```
</TabItem>
</Tabs>
## Permissions
By default, a model has no permissions, and only the admin account will be able to use it. You can enable the model by
adding permissions for a given role.
As Logical Models are currently only used for read-only purposes, you can only add select permissions.
The permissions consist of a list of columns that the role can access, and a filter that specifies which rows the role
can receive.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
Columns must be specified, though you can use `"*"` to specify that you want to allow all columns.
The filter is the same boolean expression syntax as [query filters](/queries/ms-sql-server/query-filters.mdx). To allow
all rows to be passed through to the response, you can specify an empty filter, `{}`.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>",
"permission": {
"columns": "*" | [
"column 1",
"column 2",
...
],
"filter": <boolean expression>
}
}
}
```
</TabItem>
</Tabs>
For example, to allow access to the "article" Logical Model for the "reader" role, but only for published articles, we
could use the following permission to limit the accessible rows to those where `is_published` is `true`, and then hide
that column from the list (by specifying all other columns).
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_create_logical_model_select_permission",
"args": {
"source": "default",
"name": "article",
"role": "reader",
"permission": {
"columns": [
"id",
"title",
"contents",
"date"
],
"filter": {
"is_published": {"_eq": true}
}
}
}
}
```
</TabItem>
</Tabs>
You can also drop permissions:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_drop_logical_model_select_permission",
"args": {
"source": "default",
"name": "<logical model name>",
"role": "<role name>"
}
}
```
</TabItem>
</Tabs>
## Relationships
Currently, Logical Models do not support relationships. They will be supported in a future release.

346
docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx Normal file
View File

@ -0,0 +1,346 @@
---
sidebar_label: Native Queries
sidebar_position: 4
description: Customize the Hasura GraphQL schema with native queries
keywords:
- hasura
- docs
- ms sql server
- schema
- logical models
- native queries
sidebar_class_name: beta-tag
---
import ProductBadge from '@site/src/components/ProductBadge';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# MS SQL Server: Native Queries
<div className="badge-container">
<ProductBadge standard pro ee self />
<div className="badge badge-gray heading-badge">Beta</div>
</div>
## What are Native Queries?
:::tip Supported from
Native queries are supported from `v2.26.0`.
:::
The Hasura GraphQL Engine automatically generates a GraphQL API around database objects. That includes querying,
mutating, and subscribing to data changes and events. However, sometimes we need more custom or advanced behavior that
doesn’t come out of the box.
Native Queries allows you to automatically generate a GraphQL API around raw SQL queries, giving you more flexibility
and control over your Hasura-generated GraphQL schema. They allow you to harness the full power of SQL within Hasura
without the need to create database objects that require DDL privileges.
You might find Native Queries useful for many reasons:
- Use the full power of SQL that Hasura might not provide access to through the typical table API, such as `GROUP BY`,
window functions, or scalar functions.
- Provide custom arguments to the users of your API to greatly expand its flexibility.
- Encapsulate sophisticated filtering with a query, allowing your users to provide a single argument rather than having
to understand how to manipulate the data.
- Work with the advanced features of your database to improve performance.
- Write a compatibility layer around tables, making it easier to change your API without breaking existing clients.
- Reduce duplication by moving common data manipulation into one place.
Native Queries are a Cloud and Enterprise feature of Hasura.
:::info Supported features
Currently, Hasura aggregations are not supported, but you can write the aggregation yourself as part of the query.
Relationships will be supported in a future release.
:::
## Example: excerpts of articles
We’ll start with an example. Let’s use this new feature to add some custom functionality to our Hasura API, without
needing to define a custom SQL function on the database. If you’d like some reference documentation, scroll down, and
also take a look at the [Logical Models documentation](/schema/ms-sql-server/logical-models/index.mdx).
Imagine we have some articles in a table, with content kindly donated by [Loripsum.net](https://loripsum.net/):
```sql
CREATE TABLE article(
id SERIAL NOT NULL PRIMARY KEY,
title TEXT NOT NULL,
date DATE NOT NULL,
content TEXT NOT NULL
);
INSERT INTO article(title, date, content) VALUES
('You will not believe', '2023-01-01', 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Facillimum id quidem est, inquam. Esse enim, nisi eris, non potes. Oratio me istius philosophi non offendit; Idemne, quod iucunde? Quid est enim aliud esse versutum? Non autem hoc: igitur ne illud quidem.'),
('Ten things that', '2023-02-02', 'Illi enim inter se dissentiunt. Sedulo, inquam, faciam. Simus igitur contenti his.'),
('Did you know', '2023-03-03', 'Ratio quidem vestra sic cogit. Duo Reges: constructio interrete. An nisi populari fama? Erat enim res aperta. Apparet statim, quae sint officia, quae actiones. Tum mihi Piso: Quid ergo?'),
('They just cannot', '2023-04-04', 'Itaque hic ipse iam pridem est reiectus; Quod quidem iam fit etiam in Academia. Negare non possum. Quis non odit sordidos, vanos, leves, futtiles?'),
('What on earth', '2023-05-05', 'Venit ad extremum; At certe gravius. Efficiens dici potest. Rhetorice igitur, inquam, nos mavis quam dialectice disputare? Nunc de hominis summo bono quaeritur; Rationis enim perfectio est virtus;');
```
When listing these articles in an index, we probably want to truncate the text to, let’s say, 20 characters. So let’s
create a Logical Model representing the excerpted article:
:::info Only creatable via the API
Currently, Native Queries can only be created using the API. Console and CLI support will be added in a future release.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_logical_model",
"args": {
"source": "default",
"name": "article_excerpt",
"fields": [
{
"name": "id",
"type": "integer"
},
{
"name": "title",
"type": "text"
},
{
"name": "date",
"type": "date"
},
{
"name": "excerpt",
"type": "text"
}
]
}
}
```
</TabItem>
</Tabs>
We can then track a Native Query that takes a single argument, `max_length`, and uses it to truncate the article content
(more on arguments below). We use the SQL `substring` function to truncate the function, and the `length` function to
decide whether we should use an ellipsis.
We use `{{max_length}}` to refer to the argument. We need it twice, so we simply use the argument twice.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_native_query",
"args": {
"type": "query",
"source": "default",
"root_field_name": "article_with_excerpt",
"arguments": {
"max_length": {
"type": "integer"
}
},
"returns": "article_excerpt",
"code": "SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article"
}
}
```
</TabItem>
</Tabs>
All that’s left is for us to make a GraphQL query to select some articles with excerpts using our new root field
generated in the previous API call. All we need to provide is the date range we’re interested in:
```graphql
query {
article_with_excerpt(args: { max_length: 20 }, where: { date: { _gte: "2023-03-01" } }) {
id
title
date
excerpt
}
}
```
When we run this GraphQL query, we get the following results:
```json
{
"data": {
"article_with_excerpt": [
{
"id": 3,
"title": "Did you know",
"date": "2023-03-03",
"excerpt": "Ratio quidem vestra ..."
},
{
"id": 4,
"title": "They just cannot",
"date": "2023-04-04",
"excerpt": "Itaque hic ipse iam ..."
},
{
"id": 5,
"title": "What on earth",
"date": "2023-05-05",
"excerpt": "Venit ad extremum; A..."
}
]
}
}
```
## Creating a Native Query
### 1. Create a Logical Model
In order to represent the structure of the data returned by the query, we first create a Logical Model.
:::info Permissions and Logical Models
Note that this Logical Model has no attached permissions and therefore will only be available to the admin account. See
the [Logical Model documentation](/schema/ms-sql-server/logical-models/index.mdx) for information on attaching
permissions.
:::
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_logical_model",
"args": {
"source": "default",
"name": "<name>",
"fields": [
{
"name": "<field name>",
"type": "<SQL Server field type>",
"nullable": false | true,
"description": "<optional field description>"
},
...
]
}
}
```
</TabItem>
</Tabs>
### 2. Create a Native Query
Once the Logical Model is defined, we can use it to define the query:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="api" label="API">
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_native_query",
"args": {
"source": "default",
"root_field_name": "<name>",
"type": "query",
"arguments": {
"<name>": {
"type": "<SQL Server field type>",
"nullable": false | true,
"description": "<optional field description>"
}
},
"code": "<SQL query>",
"returns": "<logical model name>"
}
}
```
</TabItem>
</Tabs>
You can use any SQL that you could potentially use in a parameterized query, with the following caveats:
- The query must currently be a single read-only SQL query.
- The query must be a valid standalone query, and not a partial query.
- The return type of the query must match with the Logical Model.
- The SQL cannot invoke a stored procedure.
#### Arguments
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the
syntax `{{argument_name}}`. This syntax resembles popular string templating languages such as Mustache, but does not use
string interpolation. Instead, it works in exactly the same way as prepared statements in the database, and so arguments
do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
This does mean that arguments cannot be used for elements of the SQL that deal with structure. For example, you cannot
use an argument to specify the name of the table in a `FROM` clause.
When making a query, the arguments are specified using the `args` parameter of the query root field.
## Using the Native Query
You can make a GraphQL request using the specified root field name just as you would any other GraphQL query. When
making a query, the arguments are specified using the `args` parameter of the query root field.
```graphql
query {
<root field name>(
[args: {"<argument name>": <argument value>, ...},]
[where: ...,]
[order_by: ..., distinct_on: ...,]
[limit: ..., offset: ...]
) {
<field 1>
<field 2>
...
}
}
```
## Query functionality
Just like tables, native queries generate GraphQL types with the ability to further break down the data. You can find
more information in the relevant documentation for [filtering](/queries/ms-sql-server/query-filters.mdx),
[sorting](/queries/ms-sql-server/sorting.mdx), and [pagination](/queries/ms-sql-server/pagination.mdx).
Subscriptions (live queries) are also supported as usual.
## Mutations
Currently, only read-only queries are supported. All queries are run in a read-only transaction where supported to
enforce this constraint.
A future release will allow mutations to be specified using native queries.
## Permissions
Native queries will inherit the permissions of the Logical Model that they return. See the
[documentation on Logical Models](/schema/ms-sql-server/logical-models/index.mdx) for an explanation of how to add
permissions.

2
docs/docs/schema/postgres/logical-models/index.mdx
View File

@ -59,7 +59,7 @@ X-Hasura-Role: admin
"fields": [
{
"name": "<field name>",
"type": "<postgres field type>",
"type": "<PostgreSQL field type>",
"nullable": false | true,
"description": "<optional field description>"
},

10
docs/docs/schema/postgres/logical-models/native-queries.mdx
View File

@ -238,7 +238,7 @@ X-Hasura-Role: admin
"fields": [
{
"name": "<field name>",
"type": "<postgres field type>",
"type": "<PostgreSQL field type>",
"nullable": false | true,
"description": "<optional field description>"
},
@ -271,7 +271,7 @@ X-Hasura-Role: admin
"type": "query",
"arguments": {
"<name>": {
"type": "<postgres field type>",
"type": "<PostgreSQL field type>",
"nullable": false | true,
"description": "<optional field description>"
}
@ -295,9 +295,9 @@ You can use any SQL that you could potentially use in a parameterized query, wit
#### Arguments
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the
syntax `{{argument_name}}`. **This syntax resembles popular string templating languages such as Mustache, but does not
use string interpolation. Instead, it works in exactly the same way as prepared statements in PostgreSQL, and so
arguments do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.**
syntax `{{argument_name}}`. This syntax resembles popular string templating languages such as Mustache, but does not use
string interpolation. Instead, it works in exactly the same way as prepared statements in the database, and so arguments
do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
This does mean that arguments cannot be used for elements of the SQL that deal with structure. For example, you cannot
use an argument to specify the name of the table in a `FROM` clause.