From bf0afdfc0c9971a8e75cbaeb2efdfd2d81a69a34 Mon Sep 17 00:00:00 2001 From: Samir Talwar Date: Wed, 21 Jun 2023 16:56:28 +0200 Subject: [PATCH] docs: Add CLI instructions for Logical Models and friends. Resolves [NDAT-732](https://hasurahq.atlassian.net/browse/NDAT-732). We were missing CLI instructions for Logical Models, Native Queries, and Stored Procedures. Now we are not. Removes the "beta" label for Native Queries too. [NDAT-732]: https://hasurahq.atlassian.net/browse/NDAT-732?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9627 GitOrigin-RevId: c132c1b4a8de5626da6b403d263a946b648c0259 --- .../schema/bigquery/logical-models/index.mdx | 145 ++++++++++++++-- .../logical-models/native-queries.mdx | 93 ++++++++++- .../ms-sql-server/logical-models/index.mdx | 145 ++++++++++++++-- .../logical-models/native-queries.mdx | 93 ++++++++++- .../logical-models/stored-procedures.mdx | 112 +++++++++++-- .../schema/postgres/logical-models/index.mdx | 155 ++++++++++++++++-- .../logical-models/native-queries.mdx | 96 +++++++++-- 7 files changed, 760 insertions(+), 79 deletions(-) diff --git a/docs/docs/schema/bigquery/logical-models/index.mdx b/docs/docs/schema/bigquery/logical-models/index.mdx index 76112d8ab48..84699c49460 100644 --- a/docs/docs/schema/bigquery/logical-models/index.mdx +++ b/docs/docs/schema/bigquery/logical-models/index.mdx @@ -36,21 +36,35 @@ Logical Models themselves, read on. ## Tracking a Logical Model -:::info Only creatable via the Console and API - -Currently, Logical Models can only be created via the API and the Console. CLI support will be added in a future -release. - -::: - + + + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + You create a logical model through the metadata API: @@ -68,7 +82,7 @@ X-Hasura-Role: admin "fields": [ { "name": "", - "type": "", + "type": "", "nullable": false | true, "description": "" }, @@ -89,12 +103,42 @@ For example, we could track a representation of an article as follows: + + + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article + fields: + id: + type: integer + nullable: false + title: + type: text + nullable: false + contents: + type: text + nullable: false + published_date: + type: date + nullable: true + is_published: + type: boolean + nullable: false +``` + + + ```http @@ -156,12 +200,21 @@ X-Hasura-Role: admin + + + + + +You can remove a Logical Model by removing it from the `metadata > databases.yaml` file. + + + You can remove a Logical Model the same way: @@ -193,15 +246,21 @@ will fail. You must remove the Native Query first. To untrack the above "article" Logical Model, we would run the following: - - + + + + +Remove the above metadata from the `metadata > databases.yaml` file. + + + ```http @@ -350,6 +409,35 @@ can receive. + + + +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, `{}`. + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: "" + permission: + columns: "*" | [ + "column 1", + "column 2", + ... + ] + filter: "" + - ... +``` + + + Columns must be specified, though you can use `"*"` to specify that you want to allow all columns. @@ -393,6 +481,32 @@ that column from the list (by specifying all other columns). + + + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: reader + permission: + columns: + - id + - title + - contents + - date + filter: + is_published: + _eq: true + - ... +``` + + + ```http @@ -428,8 +542,17 @@ You can also drop permissions: - + + + + + + +Remove the relevant permission from `metadata > databases.yaml`. + + + ```http diff --git a/docs/docs/schema/bigquery/logical-models/native-queries.mdx b/docs/docs/schema/bigquery/logical-models/native-queries.mdx index 6152e8a5b0b..bca1bba44d2 100644 --- a/docs/docs/schema/bigquery/logical-models/native-queries.mdx +++ b/docs/docs/schema/bigquery/logical-models/native-queries.mdx @@ -9,7 +9,6 @@ keywords: - schema - Logical Models - Native Queries -sidebar_class_name: beta-tag --- import ProductBadge from '@site/src/components/ProductBadge'; @@ -21,7 +20,6 @@ import Thumbnail from '@site/src/components/Thumbnail';
-
Beta
## What are Native Queries? @@ -88,13 +86,6 @@ INSERT INTO article(title, date, content) VALUES 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 Console and API - -Currently, Native Queries can be created using the Console and the API. CLI support will be added in a future -release. - -::: - @@ -111,6 +102,27 @@ Once the modal is open, fill in the form. /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article_excerpt + fields: + id: + type: integer + title: + type: text + date: + type: date + excerpt: + type: text +``` + + + ```http @@ -182,6 +194,23 @@ FROM article /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: article_with_excerpt + arguments: + max_length: + type: integer + code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article + returns: article_excerpt +``` + + + ```http @@ -285,6 +314,25 @@ Once the modal is open, fill in the forms with: + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + ```http @@ -336,6 +384,33 @@ Fill in the form with the data required: + + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: "" + arguments: + "": + type: "" + nullable: false | true + description: "" + array_relationships: + - name: "" + using: + column_mapping: + "": "" + remote_native_query: " + object_relationships: + description: "" + code: "" + returns: "" +``` + + + ```http 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 f8d1603aa0e..a4b39663c92 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/index.mdx +++ b/docs/docs/schema/ms-sql-server/logical-models/index.mdx @@ -37,21 +37,35 @@ of Logical Models themselves, read on. ## Tracking a Logical Model -:::info Only creatable via the Console and API - -Currently, Logical Models can only be created via the API and the Console. CLI support will be added in a future -release. - -::: - + + + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + You create a logical model through the metadata API: @@ -69,7 +83,7 @@ X-Hasura-Role: admin "fields": [ { "name": "", - "type": "", + "type": "", "nullable": false | true, "description": "" }, @@ -90,12 +104,42 @@ For example, we could track a representation of an article as follows: + + + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article + fields: + id: + type: integer + nullable: false + title: + type: text + nullable: false + contents: + type: text + nullable: false + published_date: + type: date + nullable: true + is_published: + type: bit + nullable: false +``` + + + ```http @@ -157,12 +201,21 @@ X-Hasura-Role: admin + + + + + +You can remove a Logical Model by removing it from the `metadata > databases.yaml` file. + + + You can remove a Logical Model the same way: @@ -195,12 +248,21 @@ To untrack the above "article" Logical Model, we would run the following: + + + + + +Remove the above metadata from the `metadata > databases.yaml` file. + + + ```http @@ -349,6 +411,35 @@ can receive. + + + +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, `{}`. + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: "" + permission: + columns: "*" | [ + "column 1", + "column 2", + ... + ] + filter: "" + - ... +``` + + + Columns must be specified, though you can use `"*"` to specify that you want to allow all columns. @@ -392,6 +483,32 @@ that column from the list (by specifying all other columns). + + + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: reader + permission: + columns: + - id + - title + - contents + - date + filter: + is_published: + _eq: true + - ... +``` + + + ```http @@ -427,8 +544,17 @@ You can also drop permissions: - + + + + + + +Remove the relevant permission from `metadata > databases.yaml`. + + + ```http @@ -447,5 +573,4 @@ X-Hasura-Role: admin ``` - diff --git a/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx b/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx index 09edaaff725..404d6de8b15 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx +++ b/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx @@ -9,7 +9,6 @@ keywords: - schema - Logical Models - Native Queries -sidebar_class_name: beta-tag --- import ProductBadge from '@site/src/components/ProductBadge'; @@ -21,7 +20,6 @@ import Thumbnail from '@site/src/components/Thumbnail';
-
Beta
## What are Native Queries? @@ -88,13 +86,6 @@ INSERT INTO article(title, date, content) VALUES 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 Console and API - -Currently, Native Queries can be created using the Console and the API. CLI support will be added in a future -release. - -::: - @@ -111,6 +102,27 @@ Once the modal is open, fill in the form. /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article_excerpt + fields: + id: + type: integer + title: + type: text + date: + type: date + excerpt: + type: text +``` + + + ```http @@ -184,6 +196,23 @@ FROM article /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: article_with_excerpt + arguments: + max_length: + type: integer + code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article + returns: article_excerpt +``` + + + ```http @@ -288,6 +317,25 @@ Once the modal is open, fill in the forms with: + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + ```http @@ -339,6 +387,33 @@ Fill in the form with the data required: + + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: "" + arguments: + "": + type: "" + nullable: false | true + description: "" + array_relationships: + - name: "" + using: + column_mapping: + "": "" + remote_native_query: " + object_relationships: + description: "" + code: "" + returns: "" +``` + + + ```http 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 index 135824d432a..708da5f7cfb 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx +++ b/docs/docs/schema/ms-sql-server/logical-models/stored-procedures.mdx @@ -7,7 +7,7 @@ keywords: - docs - ms sql server - schema - - Logical Models + - logical models - stored procedures sidebar_class_name: alpha-tag --- @@ -16,7 +16,7 @@ import ProductBadge from '@site/src/components/ProductBadge'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# MS SQL Server: stored procedures +# MS SQL Server: Stored Procedures
@@ -27,11 +27,11 @@ import TabItem from '@theme/TabItem'; :::tip Supported from -stored procedures are supported from `v2.26.0`. +Stored procedures are supported from `v2.26.0`. ::: -stored procedures can be used to track MS SQL Server +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. @@ -60,14 +60,41 @@ stored procedure. We can create a Logical Model representing the results set: -:::info Only creatable via the API +:::info Only creatable via the CLI oand API -Currently, stored procedures can only be created using the API. Console and CLI support will be added in a future +Currently, stored procedures can only be created using the CLI or API. Console support will be added in a future release. ::: + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: tables + fields: + TABLE_QUALIFIER: + type: sysname + nullable: true + TABLE_OWNER: + type: sysname + nullable: true + TABLE_NAME: + type: sysname + nullable: true + TABLE_TYPE: + type: "varchar(32)" + nullable: true + REMARKS: + type: "varchar(254)" + nullable: true +``` + + + ```http @@ -127,6 +154,25 @@ database stored procedure and the Logical Model or the arguments, an error will ::: + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + stored_procedures: + - stored_procedure: + schema: public + name: sp_tables + configuration: + exposed_as: query + arguments: + table_type: + type: varchar + returns: tables +``` + + + ```http @@ -213,6 +259,24 @@ Note that this Logical Model has no attached permissions and therefore will only ::: + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + ```http @@ -246,6 +310,28 @@ X-Hasura-Role: admin Once the Logical Model is defined, we can use it to define the query: + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + stored_procedures: + - stored_procedure: + schema: "" + name: "" + configuration: + exposed_as: query + custom_name: "" + arguments: + "": + type: "" + nullable: false | true + description: "" + returns: "" +``` + + + ```http @@ -256,20 +342,20 @@ X-Hasura-Role: admin { "type": "mssql_track_stored_procedure", "args": { - "source": , - "stored_procedure": | { "schema": , "name": }, + "source": , + "stored_procedure": | { "schema": , "name": }, "arguments": { - : { - "type": "", + "": { + "type": "", "nullable": false | true, - "description": + "description": "" } }, "configuration": { "exposed_as": "query", - "custom_name": + "custom_name": }, - "returns": + "returns": } } ``` diff --git a/docs/docs/schema/postgres/logical-models/index.mdx b/docs/docs/schema/postgres/logical-models/index.mdx index 9df97a46347..a91d9e77e66 100644 --- a/docs/docs/schema/postgres/logical-models/index.mdx +++ b/docs/docs/schema/postgres/logical-models/index.mdx @@ -38,21 +38,35 @@ Logical Models themselves, read on. ## Tracking a Logical Model -:::info Only creatable via the Console and API - -Currently, Logical Models can only be created via the API and the Console. CLI support will be added in a future -release. - -::: - + + + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + You create a logical model through the metadata API: @@ -70,7 +84,7 @@ X-Hasura-Role: admin "fields": [ { "name": "", - "type": "", + "type": "", "nullable": false | true, "description": "" }, @@ -91,12 +105,42 @@ For example, we could track a representation of an article as follows: + + + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article + fields: + id: + type: integer + nullable: false + title: + type: text + nullable: false + contents: + type: text + nullable: false + published_date: + type: date + nullable: true + is_published: + type: boolean + nullable: false +``` + + + ```http @@ -158,12 +202,21 @@ X-Hasura-Role: admin + + + + + +You can remove a Logical Model by removing it from the `metadata > databases.yaml` file. + + + You can remove a Logical Model the same way: @@ -195,6 +248,22 @@ will fail. You must remove the Native Query first. To untrack the above "article" Logical Model, we would run the following: + + + + + + + + +Remove the above metadata from the `metadata > databases.yaml` file. + + + ```http @@ -211,14 +280,6 @@ X-Hasura-Role: admin } ``` - - - - @@ -351,6 +412,35 @@ can receive. + + + +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, `{}`. + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: "" + permission: + columns: "*" | [ + "column 1", + "column 2", + ... + ] + filter: "" + - ... +``` + + + Columns must be specified, though you can use `"*"` to specify that you want to allow all columns. @@ -394,6 +484,32 @@ that column from the list (by specifying all other columns). + + + +Add the required permissions to the relevant logical model in `metadata > databases.yaml`: + +```yaml + logical_models: + - name: "" + fields: + ... + select_permissions: + - role: reader + permission: + columns: + - id + - title + - contents + - date + filter: + is_published: + _eq: true + - ... +``` + + + ```http @@ -431,6 +547,13 @@ You can also drop permissions: + + + +Remove the relevant permission from `metadata > databases.yaml`. + + + ```http diff --git a/docs/docs/schema/postgres/logical-models/native-queries.mdx b/docs/docs/schema/postgres/logical-models/native-queries.mdx index 12b1bef0921..d057f8c7c55 100644 --- a/docs/docs/schema/postgres/logical-models/native-queries.mdx +++ b/docs/docs/schema/postgres/logical-models/native-queries.mdx @@ -9,7 +9,6 @@ keywords: - schema - Logical Models - Native Queries -sidebar_class_name: beta-tag --- import ProductBadge from '@site/src/components/ProductBadge'; @@ -19,10 +18,6 @@ import Thumbnail from '@site/src/components/Thumbnail'; # Postgres: Native Queries -
-
Beta
-
- ## What are Native Queries? :::tip Supported from @@ -90,12 +85,6 @@ INSERT INTO article(title, date, content) VALUES 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 Console and API - -Currently, Native Queries can be created using the Console and the API. CLI support will be added in a future release. - -::: - @@ -112,6 +101,27 @@ Once the modal is open, fill in the form. /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + logical_models: + - name: article_excerpt + fields: + id: + type: integer + title: + type: text + date: + type: date + excerpt: + type: text +``` + + + ```http @@ -183,6 +193,23 @@ FROM article /> + + + +Add the following to the `default` database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: article_with_excerpt + arguments: + max_length: + type: integer + code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article + returns: article_excerpt +``` + + + ```http @@ -286,6 +313,25 @@ Once the modal is open, fill in the forms with: + + + +You can create a logical model by adding it to the appropriate database definition in the `metadata > databases.yaml` +file: + +```yaml + logical_models: + - name: "" + fields: + "": + type: "" + nullable: false | true + description: "" + ... +``` + + + ```http @@ -337,6 +383,33 @@ Fill in the form with the data required: + + + +Add the following to the relevant database definition in the `metadata > databases.yaml` file: + +```yaml + native_queries: + - root_field_name: "" + arguments: + "": + type: "" + nullable: false | true + description: "" + array_relationships: + - name: "" + using: + column_mapping: + "": "" + remote_native_query: " + object_relationships: + description: "" + code: "" + returns: "" +``` + + + ```http @@ -597,6 +670,7 @@ allows for mutual references. + The Native Queries in this example enable queries like: ```graphql