From dcbe163a8846b015858f4709cf478faf39a2833b Mon Sep 17 00:00:00 2001 From: Gil Mizrahi Date: Fri, 19 May 2023 18:46:33 +0300 Subject: [PATCH] docs: add documentation for stored procedures PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9211 GitOrigin-RevId: d336ccd6a811861a6f2ebd5251bd5441d0112ddb --- .../api-reference/metadata-api/actions.mdx | 2 +- .../api-reference/metadata-api/api-limits.mdx | 2 +- .../metadata-api/computed-field.mdx | 2 +- .../metadata-api/custom-functions.mdx | 2 +- .../metadata-api/custom-types.mdx | 2 +- .../metadata-api/event-triggers.mdx | 2 +- .../metadata-api/inherited-roles.mdx | 2 +- .../metadata-api/introspection.mdx | 2 +- .../metadata-api/manage-metadata.mdx | 2 +- .../metadata-api/native-queries.mdx | 6 +- .../api-reference/metadata-api/network.mdx | 2 +- .../metadata-api/observability.mdx | 2 +- .../api-reference/metadata-api/permission.mdx | 2 +- .../metadata-api/query-collections.mdx | 2 +- .../metadata-api/relationship.mdx | 2 +- .../metadata-api/remote-relationships.mdx | 2 +- .../remote-schema-permissions.mdx | 2 +- .../metadata-api/remote-schemas.mdx | 2 +- .../metadata-api/restified-endpoints.mdx | 2 +- .../metadata-api/scheduled-triggers.mdx | 2 +- .../metadata-api/stored-procedures.mdx | 92 +++++ docs/docs/api-reference/syntax-defs.mdx | 16 +- .../ms-sql-server/logical-models/index.mdx | 4 +- .../logical-models/stored-procedures.mdx | 334 ++++++++++++++++++ 24 files changed, 466 insertions(+), 24 deletions(-) create mode 100644 docs/docs/api-reference/metadata-api/stored-procedures.mdx create mode 100644 docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx diff --git a/docs/docs/api-reference/metadata-api/actions.mdx b/docs/docs/api-reference/metadata-api/actions.mdx index 62af715cac7..97526d8bc2b 100644 --- a/docs/docs/api-reference/metadata-api/actions.mdx +++ b/docs/docs/api-reference/metadata-api/actions.mdx @@ -1,6 +1,6 @@ --- sidebar_label: Actions -sidebar_position: 18 +sidebar_position: 19 description: Manage Actions with the Hasura Metadata API keywords: - hasura diff --git a/docs/docs/api-reference/metadata-api/api-limits.mdx b/docs/docs/api-reference/metadata-api/api-limits.mdx index 49039b9e5c1..efeaea18bb9 100644 --- a/docs/docs/api-reference/metadata-api/api-limits.mdx +++ b/docs/docs/api-reference/metadata-api/api-limits.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/computed-field.mdx b/docs/docs/api-reference/metadata-api/computed-field.mdx index 7f82e27ab3b..2a66d8835b0 100644 --- a/docs/docs/api-reference/metadata-api/computed-field.mdx +++ b/docs/docs/api-reference/metadata-api/computed-field.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/custom-functions.mdx b/docs/docs/api-reference/metadata-api/custom-functions.mdx index 31f392b0bb4..10a0292c6d2 100644 --- a/docs/docs/api-reference/metadata-api/custom-functions.mdx +++ b/docs/docs/api-reference/metadata-api/custom-functions.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/custom-types.mdx b/docs/docs/api-reference/metadata-api/custom-types.mdx index bc065c458a5..625f6b38e0a 100644 --- a/docs/docs/api-reference/metadata-api/custom-types.mdx +++ b/docs/docs/api-reference/metadata-api/custom-types.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/event-triggers.mdx b/docs/docs/api-reference/metadata-api/event-triggers.mdx index 9fffb52bc74..1fe43377423 100644 --- a/docs/docs/api-reference/metadata-api/event-triggers.mdx +++ b/docs/docs/api-reference/metadata-api/event-triggers.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/inherited-roles.mdx b/docs/docs/api-reference/metadata-api/inherited-roles.mdx index cdc4dda8a09..b2e84f73309 100644 --- a/docs/docs/api-reference/metadata-api/inherited-roles.mdx +++ b/docs/docs/api-reference/metadata-api/inherited-roles.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/introspection.mdx b/docs/docs/api-reference/metadata-api/introspection.mdx index 7b88973db08..63c65573162 100644 --- a/docs/docs/api-reference/metadata-api/introspection.mdx +++ b/docs/docs/api-reference/metadata-api/introspection.mdx @@ -1,6 +1,6 @@ --- sidebar_label: Introspection options -sidebar_position: 20 +sidebar_position: 21 description: Manage introspection with the Hasura Metadata API keywords: - hasura diff --git a/docs/docs/api-reference/metadata-api/manage-metadata.mdx b/docs/docs/api-reference/metadata-api/manage-metadata.mdx index 844ff661e5a..7eee1cc14e5 100644 --- a/docs/docs/api-reference/metadata-api/manage-metadata.mdx +++ b/docs/docs/api-reference/metadata-api/manage-metadata.mdx @@ -1,6 +1,6 @@ --- sidebar_label: Manage Metadata -sidebar_position: 19 +sidebar_position: 20 description: Manage Metadata with the Hasura Metadata API keywords: - hasura diff --git a/docs/docs/api-reference/metadata-api/native-queries.mdx b/docs/docs/api-reference/metadata-api/native-queries.mdx index 9e636a794a8..9dafb2a8136 100644 --- a/docs/docs/api-reference/metadata-api/native-queries.mdx +++ b/docs/docs/api-reference/metadata-api/native-queries.mdx @@ -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 | diff --git a/docs/docs/api-reference/metadata-api/network.mdx b/docs/docs/api-reference/metadata-api/network.mdx index 1dd57bfe654..450bdcb69e6 100644 --- a/docs/docs/api-reference/metadata-api/network.mdx +++ b/docs/docs/api-reference/metadata-api/network.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/observability.mdx b/docs/docs/api-reference/metadata-api/observability.mdx index 9f911b745ea..111b6e33408 100644 --- a/docs/docs/api-reference/metadata-api/observability.mdx +++ b/docs/docs/api-reference/metadata-api/observability.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/permission.mdx b/docs/docs/api-reference/metadata-api/permission.mdx index 9377126c8e3..86fb37160cf 100644 --- a/docs/docs/api-reference/metadata-api/permission.mdx +++ b/docs/docs/api-reference/metadata-api/permission.mdx @@ -1,6 +1,6 @@ --- sidebar_label: Permissions -sidebar_position: 7 +sidebar_position: 8 description: Manage permissions with the Hasura Metadata API keywords: - hasura diff --git a/docs/docs/api-reference/metadata-api/query-collections.mdx b/docs/docs/api-reference/metadata-api/query-collections.mdx index 45efa9a6da0..88dd1386572 100644 --- a/docs/docs/api-reference/metadata-api/query-collections.mdx +++ b/docs/docs/api-reference/metadata-api/query-collections.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/relationship.mdx b/docs/docs/api-reference/metadata-api/relationship.mdx index 8e8437bede3..e9cbd2fb3ee 100644 --- a/docs/docs/api-reference/metadata-api/relationship.mdx +++ b/docs/docs/api-reference/metadata-api/relationship.mdx @@ -1,6 +1,6 @@ --- sidebar_label: Relationships -sidebar_position: 6 +sidebar_position: 7 description: Use relationships with the Hasura Metadata API keywords: - hasura diff --git a/docs/docs/api-reference/metadata-api/remote-relationships.mdx b/docs/docs/api-reference/metadata-api/remote-relationships.mdx index e68050288c2..ee6955e4f1a 100644 --- a/docs/docs/api-reference/metadata-api/remote-relationships.mdx +++ b/docs/docs/api-reference/metadata-api/remote-relationships.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/remote-schema-permissions.mdx b/docs/docs/api-reference/metadata-api/remote-schema-permissions.mdx index e5e64eba013..544433832f5 100644 --- a/docs/docs/api-reference/metadata-api/remote-schema-permissions.mdx +++ b/docs/docs/api-reference/metadata-api/remote-schema-permissions.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/remote-schemas.mdx b/docs/docs/api-reference/metadata-api/remote-schemas.mdx index ccbc68d29d6..e2755b9d059 100644 --- a/docs/docs/api-reference/metadata-api/remote-schemas.mdx +++ b/docs/docs/api-reference/metadata-api/remote-schemas.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/restified-endpoints.mdx b/docs/docs/api-reference/metadata-api/restified-endpoints.mdx index 033e97b51d5..9662ac0d5ae 100644 --- a/docs/docs/api-reference/metadata-api/restified-endpoints.mdx +++ b/docs/docs/api-reference/metadata-api/restified-endpoints.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/scheduled-triggers.mdx b/docs/docs/api-reference/metadata-api/scheduled-triggers.mdx index 384dc016d5b..ebcfd1e4638 100644 --- a/docs/docs/api-reference/metadata-api/scheduled-triggers.mdx +++ b/docs/docs/api-reference/metadata-api/scheduled-triggers.mdx @@ -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 diff --git a/docs/docs/api-reference/metadata-api/stored-procedures.mdx b/docs/docs/api-reference/metadata-api/stored-procedures.mdx new file mode 100644 index 00000000000..4da9e97c2a4 --- /dev/null +++ b/docs/docs/api-reference/metadata-api/stored-procedures.mdx @@ -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": , + "stored_procedure": | { "schema": , "name": }, + "configuration": { + "exposed_as": "query", + "custom_name": + }, + "arguments": { + : { + "type": "", + "nullable": false | true, + "description": + } + }, + "returns": + } +} +``` + +### 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": "" + } +} +``` + +### 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 | diff --git a/docs/docs/api-reference/syntax-defs.mdx b/docs/docs/api-reference/syntax-defs.mdx index a79141c82bf..972b9d9ebef 100644 --- a/docs/docs/api-reference/syntax-defs.mdx +++ b/docs/docs/api-reference/syntax-defs.mdx @@ -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 `` 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 | - diff --git a/docs/docs/schema/ms-sql-server/logical-models/index.mdx b/docs/docs/schema/ms-sql-server/logical-models/index.mdx index 95fbba8d246..9926e997abf 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/index.mdx +++ b/docs/docs/schema/ms-sql-server/logical-models/index.mdx @@ -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 diff --git a/docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx b/docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx new file mode 100644 index 00000000000..d358be9beef --- /dev/null +++ b/docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx @@ -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 + +
+ +
Alpha
+
+ +## 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. + +::: + + + + +```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 + } + ] + } +} +``` + + + + +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. + +::: + + + + +```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" + } +} +``` + + + + +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. + +::: + + + + +```http +POST /v1/metadata HTTP/1.1 +Content-Type: application/json +X-Hasura-Role: admin + +{ + "type": "mssql_track_logical_model", + "args": { + "source": "default", + "name": "", + "fields": [ + { + "name": "", + "type": "", + "nullable": false | true, + "description": "" + }, + ... + ] + } +} +``` + + + + +### Step 2. Track a stored procedure + +Once the Logical Model is defined, we can use it to define the query: + + + + +```http +POST /v1/metadata HTTP/1.1 +Content-Type: application/json +X-Hasura-Role: admin + +{ + "type": "mssql_track_stored_procedure", + "args": { + "source": , + "stored_procedure": | { "schema": , "name": }, + "arguments": { + : { + "type": "", + "nullable": false | true, + "description": + } + }, + "configuration": { + "exposed_as": "query", + "custom_name": + }, + "returns": + } +} +``` + + + + +#### 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 { + ( + [args: {"": , ...},] + [where: ...,] + [order_by: ..., distinct_on: ...,] + [limit: ..., offset: ...] + ) { + + + ... + } +} +``` + +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.