docs: add documentation for stored procedures

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9211
GitOrigin-RevId: d336ccd6a811861a6f2ebd5251bd5441d0112ddb

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

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

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

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

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

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

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

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

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

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 |
 

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

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

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

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

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

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

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

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

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

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

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": <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 |

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 `<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  |
-

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

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
+
+<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.