From a358c0a7c40d39f0913bf2de5bb04179e14e0531 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Thu, 27 Oct 2022 13:44:01 +0530 Subject: [PATCH 1/3] adding doc for cli commands to add/up-date storedProcedure/view --- ...ngCliForAddingStored-proceduresAndViews.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/internals/UsingCliForAddingStored-proceduresAndViews.md diff --git a/docs/internals/UsingCliForAddingStored-proceduresAndViews.md b/docs/internals/UsingCliForAddingStored-proceduresAndViews.md new file mode 100644 index 0000000000..95add28e55 --- /dev/null +++ b/docs/internals/UsingCliForAddingStored-proceduresAndViews.md @@ -0,0 +1,119 @@ +# Adding Views/Stored-Procedure to Runtime Config JSON + +## New Options +- CLI supports some new command line options (for `add` and `update` command): +- - `--source.type` -> To Specify the type of source (tables, views, and stored-procedure), +- - `--source.params` -> To Specify parameters for Stored Procedure, +- - `--source.key-fields` -> To Specify key-fields for Table/Views. + +## Sample command +# When source is given just as a string. +`dab add MyEntity --source "dbo.my_entity" --permissions "anonymous:*"` +> preview: +``` +"MyEntity": { + "source": "dbo.my_entity", + "permissions": [ + { + "role": "anonymous", + "actions": [ "create", "read", "update" ] + } + ] +} +``` + +# When source is a stored-procedure +`dab add MyEntity --source "s001.book" --source.type "stored-procedure" --source.params "param1:123,param2:hello,param3:true" --permissions "anonymous:*"` +> preview: +``` +"MyEntity": { + "source": { + "type": "stored-procedure", + "object": "s001.book", + "parameters": { + "param1": 123, + "param2": "hello", + "param3": true + } + }, + "permissions": [ + { + "role": "anonymous", + "actions": [ "read" ] + } + ] +} +``` + +# When source is a view +`dab add MyEntity --source "s001.book" --source.type "view" --source.key-fields "col1,col2" --permissions "anonymous:*"` +> preview: +``` +"MyEntity": { + "source": { + "type": "view", + "object": "s001.book", + "key-fields": [ "col1", "col2" ] + }, + "permissions": [ + { + "role": "anonymous", + "actions": [ "read" ] + } + ] +} +``` + +# Some unique Cases: +## Conversion from one DatabaseObjectSource to another. +If the source object looks like this: +``` +{ + "object": "bookSp", + "type": "stored-procedure", + "parameters": { + "param1": "hello", + "param2": 123 + } +} +``` + +and suppose we want to make it a table and we run this command: +`dab update Book --bookTable --source.type table --source.key-fields "col1,col2"` +Result: +``` +{ + "object": "bookTable", + "type": "table", + "key-fields":["col1", "col2"] +} +``` +and we convert it back to the original one by the below command: +`dab update Book --source bookSp --source.type stored-procedure --source.parameters "param1:hello,param2:123"` + +**NOTE:** +The CLi is smart enough to recognize the non-required field, i.e, Parameters for table/view, and keyFields for Stored Procedures. +So, when a user converts a table to stored-procedure it automatically makes the keyFields `null`, similarly it makes the Parameters null when converting from stored-procedure to table/views. +If user explicitly gives parameters while converting from stored-procedure to table/view. the CLI will give an error for the same. Same with the keyfields in case of converting from table/view to stored-procedure. + +## Conversion from object to String. +suppose we want to change the initial storedProcedure object to just a string object. +`dab update Book --source bookTable --source.type table` +Result: +``` +{ + "source": "bookTable" +} +``` +**NOTE:** +If the user changes from stored-procedure to table without adding keyfields then it automatically converts it to string object rather than DatabaseObjectSource, as the default type is Table. + +what happens if we run the below command for updating the above stored-procedure: +`dab update Book --source bookView --source.type view` +Result: +``` +{ + "object": "bookView", + "type": "view" +} +``` From a52952632a56d06b4936d31a2f1557288dfad980 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Fri, 28 Oct 2022 21:36:11 +0530 Subject: [PATCH 2/3] updating getting-started docs --- docs/configuration-file.md | 21 ++++++- .../getting-started-dab-cli.md | 9 ++- ...ngCliForAddingStored-proceduresAndViews.md | 55 +++++++++++-------- 3 files changed, 59 insertions(+), 26 deletions(-) diff --git a/docs/configuration-file.md b/docs/configuration-file.md index 7b9ca2f412..480c781136 100644 --- a/docs/configuration-file.md +++ b/docs/configuration-file.md @@ -192,8 +192,27 @@ The `source` property tells Data API builder what is the underlying database obj } ``` -> **IMPORTANT**: A table or a view defined as the source must have a primary key to be usable by Data API Builder +> **NOTE**: +- A table or a view defined as the source must have a primary key to be usable by Data API Builder. +- Source can either be string or DatabaseSourceObject (with properties such as source-type, parameters, and key-fields). +- parameters is an optional property only for Stored-Procedure. +- key-fields is an optional property only for Table/view. +- By Default if `type` is not specified, it is inferred as Table. +```json +{ + "object": "bookView", + "type": "view" +} +``` + +```json +{ + "object": "bookTable", + "type": "table", + "key-fields":["col1", "col2"] +} +``` ### Relationships The `relationships` section defines how an entity is related to other exposed entities and optionally provide details on what underlying database objects can be used to support such relationships. Objects defined in the `relationship` section will be exposed as GraphQL field in the related entity. The format is the following: diff --git a/docs/getting-started/getting-started-dab-cli.md b/docs/getting-started/getting-started-dab-cli.md index a3c79efdd8..3644850e32 100644 --- a/docs/getting-started/getting-started-dab-cli.md +++ b/docs/getting-started/getting-started-dab-cli.md @@ -37,6 +37,13 @@ To add the entities to the config file with the GraphQL type and permissions def dab add --source --graphql --permissions ``` +If `source.type` is not provided, it is inferred to be Table. Accepted values are: `table`,`view`, and `stored-procedure`. +```dotnetcli +# dab add book --source dbo.books_composite_view --source.type view --source.key-fields "id,regNo" --graphql book --permissions "anonymous:*" + +dab add --source --source.type --source.key-fields --graphql --permissions +``` + ### Update entities in config To update entities which are already added to the config, run the following update command: @@ -44,7 +51,7 @@ To update entities which are already added to the config, run the following upda ```dotnetcli # dab update book --permissions "authenticate:create,update" --fields.include "id,title" -dab update --source --graphql --permissions --fields.include --fields.exclude +dab update --source --source.type --source.key-fields --graphql --permissions --fields.include --fields.exclude ``` ### Add entity relationship mappings diff --git a/docs/internals/UsingCliForAddingStored-proceduresAndViews.md b/docs/internals/UsingCliForAddingStored-proceduresAndViews.md index 95add28e55..c3f7a13b3a 100644 --- a/docs/internals/UsingCliForAddingStored-proceduresAndViews.md +++ b/docs/internals/UsingCliForAddingStored-proceduresAndViews.md @@ -2,15 +2,16 @@ ## New Options - CLI supports some new command line options (for `add` and `update` command): -- - `--source.type` -> To Specify the type of source (tables, views, and stored-procedure), -- - `--source.params` -> To Specify parameters for Stored Procedure, -- - `--source.key-fields` -> To Specify key-fields for Table/Views. + - `--source.type` -> To Specify the type of source (tables, views, and stored-procedure), + - `--source.params` -> To Specify parameters for Stored Procedure, + - `--source.key-fields` -> To Specify key-fields for Table/Views. -## Sample command -# When source is given just as a string. +## Usage +### When `source.type` is not provided `dab add MyEntity --source "dbo.my_entity" --permissions "anonymous:*"` +NOTE: By Default sourceType is inferred to be table. > preview: -``` +```json "MyEntity": { "source": "dbo.my_entity", "permissions": [ @@ -22,10 +23,11 @@ } ``` -# When source is a stored-procedure +### When `source.type` is stored-procedure `dab add MyEntity --source "s001.book" --source.type "stored-procedure" --source.params "param1:123,param2:hello,param3:true" --permissions "anonymous:*"` +**NOTE**: source-params are optional if the procedure doesn't take any params. > preview: -``` +```json "MyEntity": { "source": { "type": "stored-procedure", @@ -45,10 +47,12 @@ } ``` -# When source is a view +### When `source.type` is view `dab add MyEntity --source "s001.book" --source.type "view" --source.key-fields "col1,col2" --permissions "anonymous:*"` + +**NOTE**: key-fields are optional if the view is simple and keys are inferable > preview: -``` +```json "MyEntity": { "source": { "type": "view", @@ -64,10 +68,10 @@ } ``` -# Some unique Cases: -## Conversion from one DatabaseObjectSource to another. +## Some unique Cases: +### Conversion from one DatabaseObjectSource to another. If the source object looks like this: -``` +```json { "object": "bookSp", "type": "stored-procedure", @@ -78,40 +82,43 @@ If the source object looks like this: } ``` -and suppose we want to make it a table and we run this command: +and suppose we want to make it a table, then we need to run this command: `dab update Book --bookTable --source.type table --source.key-fields "col1,col2"` + Result: -``` +```json { "object": "bookTable", "type": "table", "key-fields":["col1", "col2"] } ``` -and we convert it back to the original one by the below command: +We can convert it back to the original one by the below command: `dab update Book --source bookSp --source.type stored-procedure --source.parameters "param1:hello,param2:123"` **NOTE:** -The CLi is smart enough to recognize the non-required field, i.e, Parameters for table/view, and keyFields for Stored Procedures. -So, when a user converts a table to stored-procedure it automatically makes the keyFields `null`, similarly it makes the Parameters null when converting from stored-procedure to table/views. -If user explicitly gives parameters while converting from stored-procedure to table/view. the CLI will give an error for the same. Same with the keyfields in case of converting from table/view to stored-procedure. +The CLI recognizes redundant fields, i.e., Parameters for table/view, and keyFields for Stored Procedures. +When a user converts a table to a stored procedure, the CLI automatically sets the keyFields property to `null`. Similarly, the CLI sets the Parameters property to `null` when converting from a stored procedure to a table or view. +When a user explicitly sets the Parameters option while converting from stored-procedure to table/view, the CLI will return an error. The CLI will similarly return an error when a user sets the keyFields option when converting from a table/view to a stored procedure. -## Conversion from object to String. +### Conversion from object to String. suppose we want to change the initial storedProcedure object to just a string object. `dab update Book --source bookTable --source.type table` + Result: -``` +```json { "source": "bookTable" } ``` **NOTE:** -If the user changes from stored-procedure to table without adding keyfields then it automatically converts it to string object rather than DatabaseObjectSource, as the default type is Table. +If the user changes from stored-procedure to table without adding keyfields then it automatically converts the value of `source` to string object from `DatabaseObjectSource` to represent the default source type of table. -what happens if we run the below command for updating the above stored-procedure: +When we run the following command to update the above stored-procedure: `dab update Book --source bookView --source.type view` + Result: -``` +```json { "object": "bookView", "type": "view" From 93895f82b216f862e810036f7d037770940c2db2 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Mon, 31 Oct 2022 11:08:18 +0530 Subject: [PATCH 3/3] updating examples --- docs/configuration-file.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/configuration-file.md b/docs/configuration-file.md index 480c781136..a77ff2b07d 100644 --- a/docs/configuration-file.md +++ b/docs/configuration-file.md @@ -199,18 +199,29 @@ The `source` property tells Data API builder what is the underlying database obj - key-fields is an optional property only for Table/view. - By Default if `type` is not specified, it is inferred as Table. +- Examples: +1. **View** ```json { "object": "bookView", - "type": "view" + "type": "view", + "key-fields":["id", "regNo"] } ``` +2. **Table with KeyFields** ```json { "object": "bookTable", "type": "table", - "key-fields":["col1", "col2"] + "key-fields":["id", "regNo"] +} +``` + +3. **Table without KeyFields** +```json +{ + "source": "bookTable" } ``` ### Relationships