Data Modeling Commands Section Rename and Reformat (#925)

Co-authored-by: Rob Dominguez <[email protected]>

Author: seanparkross

docs/data-modeling/command.mdx

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 4
-sidebar_label: "Commands modify data"
-description: "Commands allow you to modify data in your data source."
+sidebar_label: "Commands act on data"
+description: "Commands allow you to act on data in your data source."
 toc_max_heading_level: 4
 keywords:
   - command
@@ -13,17 +13,20 @@ import TabItem from "@theme/TabItem";
 import Thumbnail from "@site/src/components/Thumbnail";
 
 import CommandCreateClickHouse from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-tutorial.mdx";
-import CommandCreateClickHouseNativeMutationTutorial from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-mutation-tutorial.mdx";
-import CommandCreateClickHouseNativeMutationHowTo from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-mutation-how-to.mdx";
+import CommandCreateClickHouseNativeOperationHowTo from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx";
+import CommandCreateClickHouseNativeOperationTutorial from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-tutorial.mdx";
 import CommandCreateLambdaGo from "@site/docs/data-modeling/partials/lambda-connectors/go/_command-create-tutorial.mdx";
+import CommandCreateLambdaGoNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx";
 import CommandCreateLambdaPython from "@site/docs/data-modeling/partials/lambda-connectors/python/_command-create-tutorial.mdx";
+import CommandCreateLambdaPythonNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx";
 import CommandCreateLambdaTypescript from "@site/docs/data-modeling/partials/lambda-connectors/typescript/_command-create-tutorial.mdx";
+import CommandCreateLambdaTypescriptNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx";
 import CommandCreateMongoDB from "@site/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-tutorial.mdx";
-import CommandCreateMongoDBNativeMutationTutorial from "@site/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-mutation-tutorial.mdx";
-import CommandCreateMongoDBNativeMutationHowTo from "@site/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-mutation-how-to.mdx";
+import CommandCreateMongoDBNativeOperationHowTo from "@site/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx";
+import CommandCreateMongoDBNativeOperationTutorial from "@site/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-tutorial.mdx";
 import CommandCreatePostgreSQL from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-tutorial.mdx";
-import CommandCreatePostgreSQLNativeMutationTutorial from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-mutation-tutorial.mdx";
-import CommandCreatePostgreSQLNativeMutationHowTo from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-mutation-how-to.mdx";
+import CommandCreatePostgreSQLNativeOperationHowTo from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx";
+import CommandCreatePostgreSQLNativeOperationTutorial from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-tutorial.mdx";
 import CommandUpdateClickHouse from "@site/docs/data-modeling/partials/classic-connectors/clickHouse/_command-update-tutorial.mdx";
 import CommandUpdateLambdaGo from "@site/docs/data-modeling/partials/lambda-connectors/go/_command-update-tutorial.mdx";
 import CommandUpdateLambdaPython from "@site/docs/data-modeling/partials/lambda-connectors/python/_command-update-tutorial.mdx";
@@ -36,7 +39,7 @@ import CommandUpdatePostgreSQL from "@site/docs/data-modeling/partials/classic-c
 ## Introduction
 
 In DDN, commands represent operations in your API that can be executed such as those which modify data in your data
-sources, (inserts, updates, deletes), or custom business logic operations.
+sources, (inserts, updates, deletes), or that perform complex read operations or execute custom business logic.
 
 ## Lifecycle
 
@@ -59,6 +62,9 @@ that point.
 
 ### From a source operation
 
+Some data connectors support the ability to introspect your data source to discover the commands that can be added to
+your supergraph automatically.
+
 ```bash title="Introspect your data source:"
 ddn connector introspect <connector_name>
 ```
@@ -79,17 +85,36 @@ ddn command add <connector_link_name> "*"
 
 This will add commands with their accompanying metadata definitions to your metadata.
 
-### Via native mutation {#via-native-mutation-how-to}
+### Via native operations {#via-native-operations-how-to}
+
+Some data connectors support the ability to add commands via native operations so that you can add any operation that is
+not supported by the automatic introspection process.
+
+For classic database connectors, this will be native query code for that source. This can be, for example, a more
+complex read operation or a way to run custom business logic, which can be exposed as queries or mutations in the
+GraphQL API.
+
+For Lambda connectors, eg: (TypeScript, Go, Python, etc) this will be a function (read-only) or procedure (mutation or
+other side-effects) that can also be exposed as a query or mutation in the GraphQL API.
 
 <Tabs groupId="source-preference" className="api-tabs">
   <TabItem value="PostgreSQL" label="PostgreSQL">
-    <CommandCreatePostgreSQLNativeMutationHowTo />
+    <CommandCreatePostgreSQLNativeOperationHowTo />
   </TabItem>
   <TabItem value="MongoDB" label="MongoDB">
-    <CommandCreateMongoDBNativeMutationHowTo />
+    <CommandCreateMongoDBNativeOperationHowTo />
   </TabItem>
   <TabItem value="ClickHouse" label="ClickHouse">
-    <CommandCreateClickHouseNativeMutationHowTo />
+    <CommandCreateClickHouseNativeOperationHowTo />
+  </TabItem>
+  <TabItem value="TypeScript" label="Node.js TypeScript">
+    <CommandCreateLambdaTypescriptNativeOperationHowTo />
+  </TabItem>
+  <TabItem value="Python" label="Python">
+    <CommandCreateLambdaPythonNativeOperationHowTo />
+  </TabItem>
+  <TabItem value="Go" label="Go">
+    <CommandCreateLambdaGoNativeOperationHowTo />
   </TabItem>
 </Tabs>
 
@@ -146,28 +171,28 @@ To modify data, you first need to create a command that maps to a specific opera
   <TabItem value="ClickHouse" label="ClickHouse">
     <CommandCreateClickHouse />
   </TabItem>
-  <TabItem value="TypeScript" label="Node.js TypeScript">
-    <CommandCreateLambdaTypescript />
-  </TabItem>
-  <TabItem value="Python" label="Python">
-    <CommandCreateLambdaPython />
-  </TabItem>
-  <TabItem value="Go" label="Go">
-    <CommandCreateLambdaGo />
-  </TabItem>
 </Tabs>
 
-#### Via native mutation {#via-native-mutation-tutorials}
+#### Via native operations {#via-native-operation-tutorials}
 
 <Tabs groupId="source-preference" className="api-tabs">
   <TabItem value="PostgreSQL" label="PostgreSQL">
-    <CommandCreatePostgreSQLNativeMutationTutorial />
+    <CommandCreatePostgreSQLNativeOperationTutorial />
   </TabItem>
   <TabItem value="MongoDB" label="MongoDB">
-    <CommandCreateMongoDBNativeMutationTutorial />
+    <CommandCreateMongoDBNativeOperationTutorial />
   </TabItem>
   <TabItem value="ClickHouse" label="ClickHouse">
-    <CommandCreateClickHouseNativeMutationTutorial />
+    <CommandCreateClickHouseNativeOperationTutorial />
+  </TabItem>
+  <TabItem value="TypeScript" label="Node.js TypeScript">
+    <CommandCreateLambdaTypescript />
+  </TabItem>
+  <TabItem value="Python" label="Python">
+    <CommandCreateLambdaPython />
+  </TabItem>
+  <TabItem value="Go" label="Go">
+    <CommandCreateLambdaGo />
   </TabItem>
 </Tabs>
 

docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-mutation-how-to.mdx renamed to docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx

@@ -0,0 +1,29 @@
+In MongoDB, you can create a [native operation](/reference/connectors/mongodb/native-operations/index.mdx) by using an
+[aggregation pipeline](https://www.mongodb.com/docs/manual/core/aggregation-pipeline/) in a JSON file by adding it to
+your connector's directory.
+
+See the syntax for MongoDB native operations [here](/reference/connectors/mongodb/native-operations/syntax.mdx).
+
+Store your native operation in an appropriate directory, possibly named for the operation type, in your connector's
+directory.
+
+```sh title="Introspect your MongoDB instance:"
+ddn connector introspect <connector_name>
+```
+
+```sh title="Show the found resources:"
+ddn connector show-resources <connector_name>
+```
+
+```sh title="Then, add your model:"
+ddn command add <connector_name> <operation_name>
+```
+
+```title="Build and serve your supergraph API:"
+ddn supergraph build local
+ddn run docker-start
+```
+
+Now in your console you can run the operation with GraphQL.
+
+See the tutorial for creating a native operation in MongoDB [here](#via-native-operation-tutorials).

docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-mutation-tutorial.mdx renamed to docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-tutorial.mdx

@@ -1,18 +1,21 @@
-The process of creating a native mutation for PostgreSQL is the following.
+The process of creating a native operation for PostgreSQL is the following.
 
-Within your connector's directory, you can add a new file with a `.sql` extension to define a native mutation.
+Within your connector's directory, you can add a new file with a `.sql` extension to define a native operation.
 
-Then, use the PostgreSQL connector's plugin to add the native query to your connector's configuration:
+Then, use the PostgreSQL connector's plugin to add the native operation to your connector's configuration:
 
-```sh title="Then, use the PostgreSQL connector's plugin to add the native mutation to your connector's configuration:"
+```sh title="Then, use the PostgreSQL connector's plugin to add the native operation to your connector's configuration:"
 ddn connector plugin \
   --connector <subgraph_name>/<path-to-your-connector>/connector.yaml \
   -- \
   native-operation create \
-  --operation-path <subgraph_name>/<path-to-your-connector>/native-operations/mutations/<mutation_name>.sql \
+  --operation-path <subgraph_name>/<path-to-your-connector>/native-operations/<operation_type>/<operation_name>.sql \
   --kind mutation
 ```
 
+By specifying the `--kind mutation` flag, you are indicating that the operation is a mutation. If you specify
+`--kind query`, the operation will be a query.
+
 ```sh title="Introspect your PostgreSQL instance:"
 ddn connector introspect <connector_name>
 ```
@@ -32,4 +35,4 @@ ddn run docker-start
 
 Now in your console you can run the mutation with GraphQL.
 
-See the tutorial for creating a native mutation in PostgreSQL [here](#via-native-mutation-tutorials).
+See the tutorial for creating a native mutation in PostgreSQL [here](#via-native-operation-tutorials).

docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-mutation-how-to.mdx

@@ -0,0 +1,74 @@
+You can run whatever arbitrary code you want in your Go connector and expose it as a GraphQL mutation or query in your
+supergraph API.
+
+```sh title="Initialize a new connector and select hasura/go from the list:"
+ddn connector init my_go -i
+```
+
+```go title="Replace the functions.go contents with your own custom code:"
+package functions
+
+import (
+	"context"
+
+	"hasura-ndc.dev/ndc-go/types"
+)
+
+// InputArguments represents the input of the native operation.
+type InputArguments struct {
+	MyInput string `json:"myInput"`
+}
+
+// OutputResult represents the output of the native operation.
+type OutputResult struct {
+	MyOutput string `json:"myOutput"`
+}
+
+// ProcedureCustomCode is a native operation that can be called from the API.
+func ProcedureCustomCode(ctx context.Context, state *types.State, arguments *InputArguments) (*OutputResult, error) {
+	// Do something with the input
+	return &OutputResult{
+		MyOutput: "My output",
+	}, nil
+}
+```
+
+Using the prefix `Procedure` ensures ProcedureCustomCode() is exposed as a mutation in our API. Prefixing with
+`Function` identifies it as a function to be exposed as a query in your API.
+
+Both have typed input arguments and return strings, which the connector will use to generate the corresponding GraphQL
+schema.
+
+```bash title="Introspect the connector:"
+ddn connector introspect my_go
+```
+
+```bash title="Track the function:"
+ddn command add my_go customCode
+```
+
+```bash title="Create a new build:"
+ddn supergraph build local
+```
+
+```bash title="Start your services:"
+ddn run docker-start
+```
+
+```bash title="Open your development console:"
+ddn console --local
+```
+
+```graphql title="You can now query your native operation:"
+query MyCustomCode {
+  customCode(myInput: "My input")
+}
+```
+
+```json title="You will see a response like this:"
+{
+  "data": {
+    "myCustomCode": "My output"
+  }
+}
+```

docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx

@@ -0,0 +1,59 @@
+You can run whatever arbitrary code you want in your Python connector and expose it as a GraphQL mutation or query in
+your supergraph API.
+
+```sh title="Initalize a new connector and select hasura/python from the list:"
+ddn connector init my_py -i
+```
+
+```py title="Replace the functions.py contents with your own custom code:"
+from hasura_ndc import start
+from hasura_ndc.function_connector import FunctionConnector
+
+connector = FunctionConnector()
+
+@connector.register_query
+def my_custom_code(my_input: str) -> str:
+  # Do something with the input
+  return "My output"
+
+if __name__ == "__main__":
+  start(connector)
+```
+
+By adding the `@connector.register_query` decorator, we are indicating that this function is to be exposed as an NDC
+function which will ultimately show up as a GraphQL query. If you use `@connector.register_mutation` instead, the
+function will be exposed as an NDC procedure which will be a GraphQL mutation.
+
+```bash title="Introspect the connector:"
+ddn connector introspect my_py
+```
+
+```bash title="Track the function:"
+ddn command add my_py my_custom_code
+```
+
+```bash title="Create a new build:"
+ddn supergraph build local
+```
+
+```bash title="Start your services:"
+ddn run docker-start
+```
+
+```bash title="Open your development console:"
+ddn console --local
+```
+
+```graphql title="You can now query your native operation:"
+query MyCustomCode {
+  myCustomCode(myInput: "My input")
+}
+```
+
+```json title="You will see a response like this:"
+{
+  "data": {
+    "myCustomCode": "My output"
+  }
+}
+```