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

docs: add documentation for stored procedures

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9211
GitOrigin-RevId: d336ccd6a811861a6f2ebd5251bd5441d0112ddb
This commit is contained in:
Gil Mizrahi 2023-05-19 18:46:33 +03:00 committed by hasura-bot
parent 0623fb659a
commit dcbe163a88
24 changed files with 466 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/docs/api-reference/metadata-api/actions.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Actions
sidebar_position: 18
sidebar_position: 19
description: Manage Actions with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/api-limits.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: API Limits
sidebar_position: 22
sidebar_position: 23
description: Manage API limits configuration with the Hasura metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/computed-field.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Computed fields
sidebar_position: 10
sidebar_position: 11
description: Manage computed fields with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/custom-functions.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Custom functions
sidebar_position: 5
sidebar_position: 6
description: Manage custom functions with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/custom-types.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Custom types
sidebar_position: 17
sidebar_position: 18
description: Define custom types with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/event-triggers.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Event Triggers
sidebar_position: 11
sidebar_position: 12
description: Manage Event Triggers with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/inherited-roles.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Inherited roles
sidebar_position: 8
sidebar_position: 9
description: Manage inherited roles with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/introspection.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Introspection options
sidebar_position: 20
sidebar_position: 21
description: Manage introspection with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/manage-metadata.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Manage Metadata
sidebar_position: 19
sidebar_position: 20
description: Manage Metadata with the Hasura Metadata API
keywords:
- hasura

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

@ -60,7 +60,7 @@ 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 |
| 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 |
| arguments | false | 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 |
@ -126,7 +126,7 @@ 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 |
| 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 |
| arguments | false | 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 |
@ -192,7 +192,7 @@ 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 |
| 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 |
| arguments | false | 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 |

2
docs/docs/api-reference/metadata-api/network.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Network options
sidebar_position: 21
sidebar_position: 22
description: Manage network options with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/observability.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Observability Options
sidebar_position: 23
sidebar_position: 24
description: Manage observability options with the Hasura metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/permission.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Permissions
sidebar_position: 7
sidebar_position: 8
description: Manage permissions with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/query-collections.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Query collections
sidebar_position: 15
sidebar_position: 16
description: Manage query collections with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/relationship.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Relationships
sidebar_position: 6
sidebar_position: 7
description: Use relationships with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/remote-relationships.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Remote Relationships
sidebar_position: 14
sidebar_position: 15
description: Manage Remote Relationships with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/remote-schema-permissions.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Remote Schema permissions
sidebar_position: 9
sidebar_position: 10
description: Manage Remote Schema permissions with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/remote-schemas.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Remote Schemas
sidebar_position: 13
sidebar_position: 14
description: Manage Remote Schemas with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/restified-endpoints.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: RESTified GraphQL endpoints
sidebar_position: 16
sidebar_position: 17
description: Manage RESTified endpoints with the Hasura Metadata API
keywords:
- hasura

2
docs/docs/api-reference/metadata-api/scheduled-triggers.mdx
View File

@ -1,6 +1,6 @@
---
sidebar_label: Scheduled Triggers
sidebar_position: 12
sidebar_position: 13
description: Manage Scheduled Triggers with the Hasura Metadata API
keywords:
- hasura

92
docs/docs/api-reference/metadata-api/stored-procedures.mdx Normal file
View File

@ -0,0 +1,92 @@
---
sidebar_label: Stored Procedures
sidebar_position: 5
description: Manage Stored Procedures with the Hasura Metadata API
keywords:
- hasura
- docs
- Metadata API
- API reference
- logical models
- stored procedures
---
# Metadata API Reference: Stored Procedures
## Introduction
Track/untrack Stored Procedures in the Hasura GraphQL Engine.
:::tip Supported from
Stored Procedures are supported from v2.26.0.
:::
## mssql_track_stored_procedure {#metadata-mssql-track-stored-procedure}
`mssql_track_stored_procedure` is used to add a Stored Procedure to the GraphQL schema.
Track a Stored Procedure as follows:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_track_stored_procedure",
"args": {
"source": <source-name>,
"stored_procedure": <name> | { "schema": <schema-name>, "name": <procedure-name> },
"configuration": {
"exposed_as": "query",
"custom_name": <custom-name>
},
"arguments": {
<name>: {
"type": "<type>",
"nullable": false | true,
"description": <string>
}
},
"returns": <logical-model-name>
}
}
```
### Args syntax {#metadata-mssql-track-stored-procedure-syntax}
| Key | Required | Schema | Description |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| source | true | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database |
| stored_procedure | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the stored procedure |
| configuration | true | [StoredProcedureConfiguration](/api-reference/syntax-defs.mdx#stored-procedure-configuration) | Configuration for the Stored Procedure |
| arguments | false | Mapping from String to [StoredProcedureArgument](/api-reference/syntax-defs.mdx#stored-procedure-argument) | Configuration for each argument |
| returns | true | [LogicalModelName](/api-reference/syntax-defs.mdx#logicalmodelname) | Name of the logical model representing the resulting schema |
## mssql_untrack_stored_procedure {#metadata-mssql-untrack-stored-procedure}
`mssql_untrack_stored_procedure` is used to remove a Stored Procedure from the GraphQL schema.
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "mssql_untrack_stored_procedure",
"args": {
"source": "default",
"stored_procedure": "<name>"
}
}
```
### Args syntax {#metadata-pg-untrack-stored-procedure-syntax}
| Key | Required | Schema | Description |
| ---------------- | -------- | ------------------------------------------------------- | ---------------------------- |
| source | true | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the source database |
| stored_procedure | true | [QueryName](/api-reference/syntax-defs.mdx#queryname) | Name of the stored procedure |

16
docs/docs/api-reference/syntax-defs.mdx
View File

@ -1266,6 +1266,21 @@ via [Custom Types](/api-reference/metadata-api/custom-types.mdx)
| nullable | false | `Boolean` | True if the underlying column is nullable (default: `false`) |
| description | false | `String` | An extended description of the argument |
## Stored Procedure Argument {#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 {#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 {#function-configuration}
| Key | Required | Schema | Description |
@ -1725,4 +1740,3 @@ Table columns can be referred by prefixing `$` e.g `$id`.
| Key | required | Schema | Description |
|-----------------------|----------|----------------------------------|---------------------------------------------------------------------------|
| max_export_batch_size | false | `Integer` | Maximum number of spans allowed per export request. Default value is 512 |

4
docs/docs/schema/ms-sql-server/logical-models/index.mdx
View File

@ -8,6 +8,7 @@ keywords:
- schema
- logical models
- native queries
- stored procedures
---
import Tabs from '@theme/Tabs';
@ -26,7 +27,8 @@ 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
[Native Queries](/schema/ms-sql-server/logical-models/native-queries.mdx) and the
[Stored Procedures](/schema/ms-sql-server/logical-models/stored-procedures.mdx) features to automatically create a GraphQL API
for a native database query.
You can find examples of how to use logical models in the

334
docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx Normal file
View File

@ -0,0 +1,334 @@
---
sidebar_label: Stored Procedures
sidebar_position: 5
description: Customize the Hasura GraphQL schema with Stored Procedures
keywords:
- hasura
- docs
- ms sql server
- schema
- logical models
- stored procedures
sidebar_class_name: alpha-tag
---
import ProductBadge from '@site/src/components/ProductBadge';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# MS SQL Server: Stored Procedures
<div className="badge-container">
<ProductBadge standard pro ee self />
<div className="badge badge-gray heading-badge">Alpha</div>
</div>
## What are Stored Procedures?
:::tip Supported from
Stored Procedures are supported from `v2.26.0`.
:::
Stored Procedures can be used to track MS SQL Server
[stored procedures](https://learn.microsoft.com/en-us/sql/relational-databases/stored-procedures/stored-procedures-database-engine)
and execute them via the Hasura GraphQL Engine.
SQL Server stored procedures are built-in or user-defined Transact-SQL statements that can be used to
encapsulate some custom business logic or extend the built-in SQL functions and operators.
Stored Procedures support is a Cloud and Enterprise feature of Hasura.
:::info Supported features
Currently, only read-only stored procedures are supported, and Hasura aggregations or relationships are not supported at this time.
:::
## Example: Execute a built-in stored procedure
We’ll start with an example. Let’s use this new feature to execute a built-in stored procedure from our Hasura API.
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).
For our case, we would like to get some information about our database. Specifically, which tables are currently defined in the database.
On SQL Server we can do that by executing the
[`sp_tables`](https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-tables-transact-sql) stored procedure.
We can create a Logical Model representing the results set:
:::info Only creatable via the API
Currently, Stored Procedures 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": "mssql",
"name": "tables",
"fields": [
{
"name": "TABLE_QUALIFIER",
"type": "sysname",
"nullable": true
},
{
"name": "TABLE_OWNER",
"type": "sysname",
"nullable": true
},
{
"name": "TABLE_NAME",
"type": "sysname",
"nullable": true
},
{
"name": "TABLE_TYPE",
"type": "varchar(32)",
"nullable": true
},
{
"name": "REMARKS",
"type": "varchar(254)",
"nullable": true
}
]
}
}
```
</TabItem>
</Tabs>
We can then track a stored procedure that returns that result set. Additionally, we can add arguments
which can be passed to the stored procedure from the GraphQL API. We'll include the `table_type`
arguments which can be used to filter tables, system tables, and views.
:::info Validation during tracking is not currently supported
Currently, Stored Procedures are not checked against the Logical Model to validate that they
return the expected result set or that the arguments match with the stored procedure's arguments.
This means that if there's a mismatch between the database stored procedure and the Logical Model
or the arguments, an error will be thrown when running a 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_stored_procedure",
"args": {
"source": "mssql",
"stored_procedure": "sp_tables",
"configuration": {
"exposed_as": "query"
},
"arguments": {
"table_type": {
"type": "varchar"
}
},
"returns": "tables"
}
}
```
</TabItem>
</Tabs>
All that’s left is for us to make a GraphQL query to select the tables which are currently
defined in the database:
```graphql
query sp {
sp_tables(
args: {
table_type: "'TABLE'"
}
limit: 3
) {
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
TABLE_TYPE
}
}
```
When we run this GraphQL query, we get the following results:
```json
{
"data": {
"sp_tables": [
{
"TABLE_QUALIFIER": "master",
"TABLE_OWNER": "dbo",
"TABLE_NAME": "MSreplication_options",
"TABLE_TYPE": "TABLE"
},
{
"TABLE_QUALIFIER": "master",
"TABLE_OWNER": "dbo",
"TABLE_NAME": "spt_fallback_db",
"TABLE_TYPE": "TABLE"
},
{
"TABLE_QUALIFIER": "master",
"TABLE_OWNER": "dbo",
"TABLE_NAME": "spt_fallback_dev",
"TABLE_TYPE": "TABLE"
}
]
}
}
```
Next, we'll look at the process of tracking a stored procedure in more detail.
## Tracking a stored procedure
### Step 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>
### Step 2. Track a stored procedure
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_stored_procedure",
"args": {
"source": <source-name>,
"stored_procedure": <name> | { "schema": <schema-name>, "name": <procedure-name> },
"arguments": {
<name>: {
"type": "<type>",
"nullable": false | true,
"description": <string>
}
},
"configuration": {
"exposed_as": "query",
"custom_name": <custom-name>
},
"returns": <logical-model-name>
}
}
```
</TabItem>
</Tabs>
#### Arguments
The Stored Procedure can take arguments, which are specified in the metadata.
When making a GraphQL query, the arguments are specified using the `args` parameter of the query root field.
If the Stored Procedure does not take arguments, the `args` parameter should be omitted from the GraphQL
query.
## Using the Stored Procedure
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 {
<stored procedure name>(
[args: {"<argument name>": <argument value>, ...},]
[where: ...,]
[order_by: ..., distinct_on: ...,]
[limit: ..., offset: ...]
) {
<field 1>
<field 2>
...
}
}
```
Currently running a Stored Procedure has the following caveats:
- The stored procedure must currently be read-only.
- The return type of the query must match with the Logical Model.
## Query functionality
Just like tables, Stored Procedures 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).
## Mutations
Currently, only read-only stored procedures are supported. All stored procedures are run in a read-only
transaction where supported to enforce this constraint.
A future release will allow mutations to be specified using Stored Procedures.
## Permissions
Stored Procedures 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.