From ac58f1666d54528561631b90093f3384bc1e75ed Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Mon, 14 Oct 2024 14:35:02 +0530
Subject: [PATCH 1/7] feat(snippet): add example for @dbquery with SQL queries

---
 dbquery/custom-query/README.md           | 22 +++++++++
 dbquery/custom-query/api.graphql         | 54 ++++++++++++++++++++++
 dbquery/custom-query/config.yaml         |  4 ++
 dbquery/custom-query/index.graphql       |  3 ++
 dbquery/custom-query/operations.graphql  | 17 +++++++
 dbquery/custom-query/stepzen.config.json |  4 ++
 dbquery/custom-query/tests/Test.js       | 58 ++++++++++++++++++++++++
 7 files changed, 162 insertions(+)
 create mode 100644 dbquery/custom-query/README.md
 create mode 100644 dbquery/custom-query/api.graphql
 create mode 100644 dbquery/custom-query/config.yaml
 create mode 100644 dbquery/custom-query/index.graphql
 create mode 100644 dbquery/custom-query/operations.graphql
 create mode 100644 dbquery/custom-query/stepzen.config.json
 create mode 100644 dbquery/custom-query/tests/Test.js

diff --git a/dbquery/custom-query/README.md b/dbquery/custom-query/README.md
new file mode 100644
index 0000000..1d09b0b
--- /dev/null
+++ b/dbquery/custom-query/README.md
@@ -0,0 +1,22 @@
+# @dbquery Example Snippet
+
+This example demonstrates how to use the `@dbquery` directive with custom SQL queries for `Customer` data in StepZen.
+
+## Files
+
+- **api.graphql**: Contains the GraphQL schema for querying `Customer` objects using custom SQL queries.
+- **config.yaml**: Database configuration, including connection URI.
+- **index.graphql**: Entry point schema file.
+- **operations.graphql**: Sample queries to test the `@dbquery` directive.
+- **stepzen.config.json**: Configuration for the StepZen endpoint.
+
+## Prerequisites
+
+- A PostgreSQL database with a `customer` table containing `id`, `name`, and `email` fields.
+- Replace the `uri` in `config.yaml` with your database connection details.
+
+## Usage
+
+1. Deploy the schema using StepZen.
+2. Use the sample queries in `operations.graphql` to test the `@dbquery` functionality.
+3. Adjust the queries as needed to fit your database schema.
diff --git a/dbquery/custom-query/api.graphql b/dbquery/custom-query/api.graphql
new file mode 100644
index 0000000..c9894d8
--- /dev/null
+++ b/dbquery/custom-query/api.graphql
@@ -0,0 +1,54 @@
+# This example shows how @dbquery is configured for custom SQL queries with Customer data.
+
+"""
+Sample Customer type.
+"""
+type Customer {
+  id: ID!
+  name: String
+  email: String
+}
+
+"""
+`Customer` queries a mock `Customer` object from a demo PostgreSQL database.
+The data is fetched using custom SQL queries.
+"""
+type Query {
+    # Fetches all customers.
+  getAllCustomers: [Customer]
+    @dbquery(
+      query: "SELECT id, name, email FROM customer"
+      type: "postgresql"
+      configuration: "postgresql_config"
+    )
+  # Fetches a customer by their ID.
+getCustomerById(id: Int!): Customer
+    @dbquery(
+      query: "SELECT id, name, email FROM customer WHERE id = $1"
+      type: "postgresql"
+      configuration: "postgresql_config"
+    )
+
+  
+  # Searches customers by name using a pattern match.
+  searchCustomersByName(name: String!): [Customer]
+    @dbquery(
+      query: "SELECT id, name, email FROM customer WHERE name LIKE '%' ||  $1 || '%'"
+      type: "postgresql"
+      configuration: "postgresql_config"
+    )
+}
+type Mutation {
+  # Updates a customer's email by their ID.
+  updateCustomerEmail(id: Int!, newEmail: String!): Customer
+    @dbquery(
+      query: """
+      UPDATE customer
+      SET email = $2
+      WHERE id = $1
+      RETURNING id, name, email
+      """
+      type: "postgresql"
+      configuration: "postgresql_config"
+    )
+}
\ No newline at end of file
diff --git a/dbquery/custom-query/config.yaml b/dbquery/custom-query/config.yaml
new file mode 100644
index 0000000..aba23c4
--- /dev/null
+++ b/dbquery/custom-query/config.yaml
@@ -0,0 +1,4 @@
+configurationset:
+  - configuration:
+      name: postgresql_config
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
\ No newline at end of file
diff --git a/dbquery/custom-query/index.graphql b/dbquery/custom-query/index.graphql
new file mode 100644
index 0000000..956ed98
--- /dev/null
+++ b/dbquery/custom-query/index.graphql
@@ -0,0 +1,3 @@
+schema @sdl(files: ["api.graphql"]) {
+  query: Query
+}
diff --git a/dbquery/custom-query/operations.graphql b/dbquery/custom-query/operations.graphql
new file mode 100644
index 0000000..1b6077c
--- /dev/null
+++ b/dbquery/custom-query/operations.graphql
@@ -0,0 +1,17 @@
+# Query to get a customer by ID
+query GetCustomerById {
+  getCustomerById(id: 1) {
+    id
+    name
+    email
+  }
+}
+
+# Query to search customers by name
+query SearchCustomersByName {
+  searchCustomersByName(name: "John") {
+    id
+    name
+    email
+  }
+}
diff --git a/dbquery/custom-query/stepzen.config.json b/dbquery/custom-query/stepzen.config.json
new file mode 100644
index 0000000..4f60baa
--- /dev/null
+++ b/dbquery/custom-query/stepzen.config.json
@@ -0,0 +1,4 @@
+{
+    "endpoint": "api/miscellaneous"
+  }
+  
\ No newline at end of file
diff --git a/dbquery/custom-query/tests/Test.js b/dbquery/custom-query/tests/Test.js
new file mode 100644
index 0000000..25f19c9
--- /dev/null
+++ b/dbquery/custom-query/tests/Test.js
@@ -0,0 +1,58 @@
+const fs = require("fs");
+const path = require("node:path");
+const {
+  deployAndRun,
+  stepzen,
+  getTestDescription,
+} = require("../../../tests/gqltest.js");
+
+testDescription = getTestDescription("snippets", __dirname);
+
+// Read the GraphQL operations from the operations file
+const requestsFile = path.join(path.dirname(__dirname), "operations.graphql");
+const requests = fs.readFileSync(requestsFile, "utf8").toString();
+
+describe(testDescription, function () {
+  const tests = [
+    {
+      label: "fetch customer by ID",
+      query: requests,
+      operationName: "GetCustomerById",
+      variables: { 
+        id: 1 
+      },
+      expected: {
+        getCustomerById: {
+          id: "1",
+          name: "Lucas Bill",
+          email: "lucas@example.com"
+        }
+      },
+    },
+    {
+      label: "search customers by name pattern",
+      query: requests,
+      operationName: "SearchCustomersByName",
+      variables: {
+        name: "John"
+      },
+      expected: {
+        searchCustomersByName: [
+          {
+            id: "2",
+            name: "John Doe",
+            email: "john@example.com"
+          },
+          {
+            id: "5",
+            name: "Johnny Smith",
+            email: "johnny@example.com"
+          }
+        ]
+      },
+    },
+  ];
+  
+  // Run the tests against the deployed schema
+  return deployAndRun(__dirname, tests, stepzen.admin);
+});

From 6ce966ec3857259373de4437f34252b32ae3a2bf Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Tue, 15 Oct 2024 14:08:59 +0530
Subject: [PATCH 2/7] feat(snippet): add example for @dbquery with SQL queries

---
 dbquery/custom-query/README.md          |  2 +-
 dbquery/custom-query/operations.graphql |  9 ++++++
 dbquery/custom-query/tests/Test.js      | 40 +++++++++++++++++--------
 3 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/dbquery/custom-query/README.md b/dbquery/custom-query/README.md
index 1d09b0b..2b92990 100644
--- a/dbquery/custom-query/README.md
+++ b/dbquery/custom-query/README.md
@@ -1,4 +1,4 @@
-# @dbquery Example Snippet
+# @dbquery SQL query Snippet
 
 This example demonstrates how to use the `@dbquery` directive with custom SQL queries for `Customer` data in StepZen.
 
diff --git a/dbquery/custom-query/operations.graphql b/dbquery/custom-query/operations.graphql
index 1b6077c..bc4bbc6 100644
--- a/dbquery/custom-query/operations.graphql
+++ b/dbquery/custom-query/operations.graphql
@@ -15,3 +15,12 @@ query SearchCustomersByName {
     email
   }
 }
+
+# Query to get all customers
+query GetAllCustomers {
+  getAllCustomers {
+    id
+    name
+    email
+  }
+}
diff --git a/dbquery/custom-query/tests/Test.js b/dbquery/custom-query/tests/Test.js
index 25f19c9..e4dad77 100644
--- a/dbquery/custom-query/tests/Test.js
+++ b/dbquery/custom-query/tests/Test.js
@@ -13,19 +13,40 @@ const requestsFile = path.join(path.dirname(__dirname), "operations.graphql");
 const requests = fs.readFileSync(requestsFile, "utf8").toString();
 
 describe(testDescription, function () {
+
   const tests = [
+    {
+      label: "fetch all customers",
+      query: requests,
+      operationName: "GetAllCustomers",
+      variables: {},
+      expected: {
+        getAllCustomers: [
+          { id: "1", name: "Lucas Bill                                        ", email: "lucas.bill@example.com                            " },
+          { id: "2", name: "Mandy Jones                                       ", email: "mandy.jones@example.com                           " },
+          { id: "3", name: "Salim Ali                                         ", email: "salim.ali@example.com                             " },
+          { id: "4", name: "Jane Xiu                                          ", email: "jane.xiu@example.com                              " },
+          { id: "5", name: "John Doe                                          ", email: "john.doe@example.com                              " },
+          { id: "6", name: "Jane Smith                                        ", email: "jane.smith@example.com                            " },
+          { id: "7", name: "Sandeep Bhushan                                   ", email: "sandeep.bhushan@example.com                       " },
+          { id: "8", name: "George Han                                        ", email: "george.han@example.com                            " },
+          { id: "9", name: "Asha Kumari                                       ", email: "asha.kumari@example.com                           " },
+          { id: "10", name: "Salma Khan                                        ", email: "salma.khan@example.com                            " }
+        ]
+      },
+    },
     {
       label: "fetch customer by ID",
       query: requests,
       operationName: "GetCustomerById",
       variables: { 
-        id: 1 
+        id: 1  
       },
       expected: {
         getCustomerById: {
           id: "1",
-          name: "Lucas Bill",
-          email: "lucas@example.com"
+          name: "Lucas Bill                                        ",
+          email: "lucas.bill@example.com                            "
         }
       },
     },
@@ -38,21 +59,16 @@ describe(testDescription, function () {
       },
       expected: {
         searchCustomersByName: [
-          {
-            id: "2",
-            name: "John Doe",
-            email: "john@example.com"
-          },
-          {
+          { 
             id: "5",
-            name: "Johnny Smith",
-            email: "johnny@example.com"
+            email: "john.doe@example.com                              ",
+            name: "John Doe                                          "
           }
         ]
       },
     },
   ];
-  
+
   // Run the tests against the deployed schema
   return deployAndRun(__dirname, tests, stepzen.admin);
 });

From f79403d23a2552ae2d3dc5caf9df21008c063ff9 Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Wed, 16 Oct 2024 12:32:39 +0530
Subject: [PATCH 3/7] feat(snippet): add example for @dbquery with SQL queries

---
 dbquery/custom-query/api.graphql | 45 ++++++++++++++++----------------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/dbquery/custom-query/api.graphql b/dbquery/custom-query/api.graphql
index c9894d8..6b1a58e 100644
--- a/dbquery/custom-query/api.graphql
+++ b/dbquery/custom-query/api.graphql
@@ -12,43 +12,42 @@ type Customer {
 """
 `Customer` queries a mock `Customer` object from a demo PostgreSQL database.
 The data is fetched using custom SQL queries.
+
+Table structure for 'customer':
+
+  CREATE TABLE customer (
+    id SERIAL PRIMARY KEY,          -- Unique identifier with sequence
+    name CHARACTER(50) NOT NULL,    -- Customer's name, max 50 characters
+    email CHARACTER(50) NOT NULL,   -- Customer's email, max 50 characters, must be unique
+    CONSTRAINT customer_email_key UNIQUE (email)  -- Unique constraint on email
+  );
+
+  Foreign key references:
+    - customeraddress(customerid) references customer(id)
+    - "order"(customerid) references customer(id)
 """
 type Query {
-    # Fetches all customers.
+  # Fetches all customers.
   getAllCustomers: [Customer]
     @dbquery(
-      query: "SELECT id, name, email FROM customer"
-      type: "postgresql"
+      query: "SELECT id, name, email FROM customer",
+      type: "postgresql",
       configuration: "postgresql_config"
     )
+
   # Fetches a customer by their ID.
-getCustomerById(id: Int!): Customer
+  getCustomerById(id: Int!): Customer
     @dbquery(
-      query: "SELECT id, name, email FROM customer WHERE id = $1"
-      type: "postgresql"
+      query: "SELECT id, name, email FROM customer WHERE id = $1",
+      type: "postgresql",
       configuration: "postgresql_config"
     )
 
-  
   # Searches customers by name using a pattern match.
   searchCustomersByName(name: String!): [Customer]
     @dbquery(
-      query: "SELECT id, name, email FROM customer WHERE name LIKE '%' ||  $1 || '%'"
-      type: "postgresql"
+      query: "SELECT id, name, email FROM customer WHERE name LIKE '%' || $1 || '%'",
+      type: "postgresql",
       configuration: "postgresql_config"
     )
 }
-type Mutation {
-  # Updates a customer's email by their ID.
-  updateCustomerEmail(id: Int!, newEmail: String!): Customer
-    @dbquery(
-      query: """
-      UPDATE customer
-      SET email = $2
-      WHERE id = $1
-      RETURNING id, name, email
-      """
-      type: "postgresql"
-      configuration: "postgresql_config"
-    )
-}
\ No newline at end of file

From 301ebce1b8094b0ea13d8efdeeec6ee3f146223a Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Thu, 17 Oct 2024 11:50:37 +0530
Subject: [PATCH 4/7] chore: readme updated with specific details

---
 dbquery/custom-query/README.md          | 73 ++++++++++++++++++++-----
 dbquery/custom-query/api.graphql        | 15 +----
 dbquery/custom-query/config.yaml        |  3 +-
 dbquery/custom-query/operations.graphql | 21 ++-----
 dbquery/custom-query/tests/Test.js      | 21 +------
 5 files changed, 70 insertions(+), 63 deletions(-)

diff --git a/dbquery/custom-query/README.md b/dbquery/custom-query/README.md
index 2b92990..a3a8ac8 100644
--- a/dbquery/custom-query/README.md
+++ b/dbquery/custom-query/README.md
@@ -1,22 +1,65 @@
-# @dbquery SQL query Snippet
 
-This example demonstrates how to use the `@dbquery` directive with custom SQL queries for `Customer` data in StepZen.
+# SQL Queries with `@dbquery`
 
-## Files
+This snippet demonstrates how to configure the `@dbquery` directive for custom SQL queries.
 
-- **api.graphql**: Contains the GraphQL schema for querying `Customer` objects using custom SQL queries.
-- **config.yaml**: Database configuration, including connection URI.
-- **index.graphql**: Entry point schema file.
-- **operations.graphql**: Sample queries to test the `@dbquery` directive.
-- **stepzen.config.json**: Configuration for the StepZen endpoint.
+## Getting Started
 
-## Prerequisites
+[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment) the StepZen command line interface.
 
-- A PostgreSQL database with a `customer` table containing `id`, `name`, and `email` fields.
-- Replace the `uri` in `config.yaml` with your database connection details.
+To run these examples,
 
-## Usage
+- `git clone` this repo
+- Change to the right working directory.
+- run `stepzen deploy`
 
-1. Deploy the schema using StepZen.
-2. Use the sample queries in `operations.graphql` to test the `@dbquery` functionality.
-3. Adjust the queries as needed to fit your database schema.
+This example uses a demo database filled with mock data, you can inspect the `config.yaml` file to find the credentials for this database. Also you can configure the connection in the `config.yaml` file by providing your database credentials.
+
+Here’s a more generalized and specific description of the `@dbquery` directive functionality without referring to any particular data:
+
+---
+
+## The `@dbquery` Directive with SQL Query
+
+The `@dbquery` directive in StepZen is used to connect your GraphQL API to databases and allows you to execute custom SQL queries within your schema. It supports various database types, such as MySQL, PostgreSQL, MSSQL, and Snowflake.
+
+In this snippet, the `query` argument is used to define custom SQL queries for more control over the data being fetched. The functionality of the `query` argument allows for:
+
+- Running complex SQL queries directly from GraphQL fields.
+- Retrieving data from specific columns or joining multiple tables based on your query requirements.
+- Filtering and querying data using SQL syntax when database field names or structures differ from the GraphQL schema.
+
+The `query` argument provides the flexibility to write any SQL statement, while the **configuration** argument references the connection settings defined in the `config.yaml` file.
+
+For example, a query may look like this:
+
+```graphql
+@dbquery(
+  query: "SELECT column1, column2 FROM your_table WHERE condition = $1",
+  type: "postgresql",
+  configuration: "your_config"
+)
+```
+
+This allows you to fetch exactly the data you need, based on the custom SQL query provided. You can adjust the queries to match your database schema and use case.
+
+## Try it Out!
+
+Deploy the schema from `dbquery/pagination` relative to the repository's root directory:
+
+```
+stepzen deploy
+```
+
+Run the [sample operations](operations.graphql):
+
+- **Fetch all customers**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customers
+  ```
+
+- **Fetch a customer by ID**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customer --var id=1
+  ```
+  
\ No newline at end of file
diff --git a/dbquery/custom-query/api.graphql b/dbquery/custom-query/api.graphql
index 6b1a58e..804ec37 100644
--- a/dbquery/custom-query/api.graphql
+++ b/dbquery/custom-query/api.graphql
@@ -22,13 +22,10 @@ Table structure for 'customer':
     CONSTRAINT customer_email_key UNIQUE (email)  -- Unique constraint on email
   );
 
-  Foreign key references:
-    - customeraddress(customerid) references customer(id)
-    - "order"(customerid) references customer(id)
 """
 type Query {
   # Fetches all customers.
-  getAllCustomers: [Customer]
+  customers: [Customer]
     @dbquery(
       query: "SELECT id, name, email FROM customer",
       type: "postgresql",
@@ -36,18 +33,10 @@ type Query {
     )
 
   # Fetches a customer by their ID.
-  getCustomerById(id: Int!): Customer
+  customer(id: Int!): Customer
     @dbquery(
       query: "SELECT id, name, email FROM customer WHERE id = $1",
       type: "postgresql",
       configuration: "postgresql_config"
     )
-
-  # Searches customers by name using a pattern match.
-  searchCustomersByName(name: String!): [Customer]
-    @dbquery(
-      query: "SELECT id, name, email FROM customer WHERE name LIKE '%' || $1 || '%'",
-      type: "postgresql",
-      configuration: "postgresql_config"
-    )
 }
diff --git a/dbquery/custom-query/config.yaml b/dbquery/custom-query/config.yaml
index aba23c4..b2107c5 100644
--- a/dbquery/custom-query/config.yaml
+++ b/dbquery/custom-query/config.yaml
@@ -1,4 +1,5 @@
 configurationset:
   - configuration:
       name: postgresql_config
-      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
\ No newline at end of file
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
+      
\ No newline at end of file
diff --git a/dbquery/custom-query/operations.graphql b/dbquery/custom-query/operations.graphql
index bc4bbc6..9793068 100644
--- a/dbquery/custom-query/operations.graphql
+++ b/dbquery/custom-query/operations.graphql
@@ -1,24 +1,15 @@
-# Query to get a customer by ID
-query GetCustomerById {
-  getCustomerById(id: 1) {
+# Retrieve a specific customer by ID
+query Customer {
+  customer(id: 1) {
     id
     name
     email
   }
 }
 
-# Query to search customers by name
-query SearchCustomersByName {
-  searchCustomersByName(name: "John") {
-    id
-    name
-    email
-  }
-}
-
-# Query to get all customers
-query GetAllCustomers {
-  getAllCustomers {
+# Retrieve all customers in the system
+query Customers {
+  customers {
     id
     name
     email
diff --git a/dbquery/custom-query/tests/Test.js b/dbquery/custom-query/tests/Test.js
index e4dad77..ff8f2e9 100644
--- a/dbquery/custom-query/tests/Test.js
+++ b/dbquery/custom-query/tests/Test.js
@@ -18,7 +18,7 @@ describe(testDescription, function () {
     {
       label: "fetch all customers",
       query: requests,
-      operationName: "GetAllCustomers",
+      operationName: "Customers",
       variables: {},
       expected: {
         getAllCustomers: [
@@ -38,7 +38,7 @@ describe(testDescription, function () {
     {
       label: "fetch customer by ID",
       query: requests,
-      operationName: "GetCustomerById",
+      operationName: "Customer",
       variables: { 
         id: 1  
       },
@@ -50,23 +50,6 @@ describe(testDescription, function () {
         }
       },
     },
-    {
-      label: "search customers by name pattern",
-      query: requests,
-      operationName: "SearchCustomersByName",
-      variables: {
-        name: "John"
-      },
-      expected: {
-        searchCustomersByName: [
-          { 
-            id: "5",
-            email: "john.doe@example.com                              ",
-            name: "John Doe                                          "
-          }
-        ]
-      },
-    },
   ];
 
   // Run the tests against the deployed schema

From fac6e75b61a76ab376bb39411657766a7b268a5e Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Thu, 17 Oct 2024 12:04:03 +0530
Subject: [PATCH 5/7] chore: readme updated with specific details

---
 dbquery/custom-query/tests/Test.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/dbquery/custom-query/tests/Test.js b/dbquery/custom-query/tests/Test.js
index ff8f2e9..692762b 100644
--- a/dbquery/custom-query/tests/Test.js
+++ b/dbquery/custom-query/tests/Test.js
@@ -21,7 +21,7 @@ describe(testDescription, function () {
       operationName: "Customers",
       variables: {},
       expected: {
-        getAllCustomers: [
+        customers: [
           { id: "1", name: "Lucas Bill                                        ", email: "lucas.bill@example.com                            " },
           { id: "2", name: "Mandy Jones                                       ", email: "mandy.jones@example.com                           " },
           { id: "3", name: "Salim Ali                                         ", email: "salim.ali@example.com                             " },
@@ -43,7 +43,7 @@ describe(testDescription, function () {
         id: 1  
       },
       expected: {
-        getCustomerById: {
+        customer: {
           id: "1",
           name: "Lucas Bill                                        ",
           email: "lucas.bill@example.com                            "

From 25089fcf0b3bd3692b34b6cd702b7aebdf53c10c Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Wed, 23 Oct 2024 14:05:10 +0530
Subject: [PATCH 6/7] fix: Enhance comments in api.graphql to clarify
 argument-to-variable mapping and @dbquery usage

---
 dbquery/custom-query/api.graphql        | 76 +++++++++++++++++--------
 dbquery/custom-query/config.yaml        |  3 +-
 dbquery/custom-query/operations.graphql |  6 +-
 3 files changed, 57 insertions(+), 28 deletions(-)

diff --git a/dbquery/custom-query/api.graphql b/dbquery/custom-query/api.graphql
index 804ec37..55649ff 100644
--- a/dbquery/custom-query/api.graphql
+++ b/dbquery/custom-query/api.graphql
@@ -1,19 +1,22 @@
 # This example shows how @dbquery is configured for custom SQL queries with Customer data.
 
 """
-Sample Customer type.
+Represents a customer in the system, stored in the 'customer' table of a PostgreSQL database.
+Each customer has an ID, name, and email. The 'Customer' type maps directly to the
+corresponding table fields.
 """
 type Customer {
-  id: ID!
-  name: String
-  email: String
+    id: ID!
+    name: String
+    email: String
 }
 
 """
-`Customer` queries a mock `Customer` object from a demo PostgreSQL database.
-The data is fetched using custom SQL queries.
+Defines the root-level queries for fetching customer data.
+These queries use the `@dbquery` directive to execute custom SQL queries.
+The SQL queries include parameter markers, which correspond to the GraphQL field arguments.
 
-Table structure for 'customer':
+The 'customer' table in PostgreSQL has the following structure:
 
   CREATE TABLE customer (
     id SERIAL PRIMARY KEY,          -- Unique identifier with sequence
@@ -21,22 +24,49 @@ Table structure for 'customer':
     email CHARACTER(50) NOT NULL,   -- Customer's email, max 50 characters, must be unique
     CONSTRAINT customer_email_key UNIQUE (email)  -- Unique constraint on email
   );
-
+These queries demonstrate basic SQL interactions with this table.
 """
 type Query {
-  # Fetches all customers.
-  customers: [Customer]
-    @dbquery(
-      query: "SELECT id, name, email FROM customer",
-      type: "postgresql",
-      configuration: "postgresql_config"
-    )
-
-  # Fetches a customer by their ID.
-  customer(id: Int!): Customer
-    @dbquery(
-      query: "SELECT id, name, email FROM customer WHERE id = $1",
-      type: "postgresql",
-      configuration: "postgresql_config"
-    )
+    """
+    Fetches a list of all customers from the database.
+
+    The custom SQL query retrieves the `id`, `name`, and `email` fields from the 'customer' table.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, it fetches all records from the 'customer' table.
+    - `type`: Specifies the type of database being queried. In this case, it’s a PostgreSQL database.
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This query does not take any arguments, and hence there are no parameter markers in the SQL query.
+    The SQL query is static, always returning all customers from the database.
+    """
+    customers: [Customer]
+        @dbquery(
+            query: "SELECT id, name, email FROM customer"
+            type: "postgresql"
+            configuration: "postgresql_config"
+        )
+
+    """
+    Fetches a single customer by their ID from the database.
+
+    **Field Argument to Parameter Marker Mapping**:
+    - The `id` argument provided in the GraphQL query maps to the `$1` marker in the SQL query.
+    - SQL queries typically use numbered markers (e.g., `$1`, `$2`, etc.) for parameterized inputs. The number refers to the position of the argument in the query.
+    - When a query is executed, the value passed to the `id` argument in GraphQL (via variables) will replace the `$1` marker in the SQL query.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, the customer data is fetched based on the provided `id` value.
+      - The `$1` marker is a placeholder for the value of the `id` argument, which is passed as a variable when executing the query.
+    - `type`: Specifies the type of database being queried (PostgreSQL).
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This query requires an `id` argument as input, which is passed as a variable from the GraphQL query. The variable's value is used to fetch the corresponding customer from the database.
+    """
+    customer(id: Int!): Customer
+        @dbquery(
+            query: "SELECT id, name, email FROM customer WHERE id = $1"
+            type: "postgresql"
+            configuration: "postgresql_config"
+        )
 }
diff --git a/dbquery/custom-query/config.yaml b/dbquery/custom-query/config.yaml
index b2107c5..aba23c4 100644
--- a/dbquery/custom-query/config.yaml
+++ b/dbquery/custom-query/config.yaml
@@ -1,5 +1,4 @@
 configurationset:
   - configuration:
       name: postgresql_config
-      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
-      
\ No newline at end of file
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
\ No newline at end of file
diff --git a/dbquery/custom-query/operations.graphql b/dbquery/custom-query/operations.graphql
index 9793068..2ebfba2 100644
--- a/dbquery/custom-query/operations.graphql
+++ b/dbquery/custom-query/operations.graphql
@@ -1,6 +1,6 @@
-# Retrieve a specific customer by ID
-query Customer {
-  customer(id: 1) {
+# Retrieve a specific customer by ID using a variable
+query Customer($id: Int!) {
+  customer(id: $id) {
     id
     name
     email

From 8f9a6f0c7a9c1e772dd7b60557cc626a3b46bacd Mon Sep 17 00:00:00 2001
From: Aswany Augustine <Aswany.Augustine@ibm.com>
Date: Mon, 28 Oct 2024 21:14:49 +0530
Subject: [PATCH 7/7] feat(snippet): add example for @dbquery with SQL queries

---
 dbquery/custom-query/README.md   | 2 +-
 dbquery/custom-query/api.graphql | 9 ++++-----
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/dbquery/custom-query/README.md b/dbquery/custom-query/README.md
index a3a8ac8..6e902d1 100644
--- a/dbquery/custom-query/README.md
+++ b/dbquery/custom-query/README.md
@@ -45,7 +45,7 @@ This allows you to fetch exactly the data you need, based on the custom SQL quer
 
 ## Try it Out!
 
-Deploy the schema from `dbquery/pagination` relative to the repository's root directory:
+Deploy the schema from `dbquery/custom-query` relative to the repository's root directory:
 
 ```
 stepzen deploy
diff --git a/dbquery/custom-query/api.graphql b/dbquery/custom-query/api.graphql
index 55649ff..ea7ff1b 100644
--- a/dbquery/custom-query/api.graphql
+++ b/dbquery/custom-query/api.graphql
@@ -37,7 +37,7 @@ type Query {
     - `type`: Specifies the type of database being queried. In this case, it’s a PostgreSQL database.
     - `configuration`: References the database configuration (connection details) in StepZen.
 
-    This query does not take any arguments, and hence there are no parameter markers in the SQL query.
+    This field does not take any arguments, and hence there are no parameter markers in the SQL query.
     The SQL query is static, always returning all customers from the database.
     """
     customers: [Customer]
@@ -51,9 +51,8 @@ type Query {
     Fetches a single customer by their ID from the database.
 
     **Field Argument to Parameter Marker Mapping**:
-    - The `id` argument provided in the GraphQL query maps to the `$1` marker in the SQL query.
-    - SQL queries typically use numbered markers (e.g., `$1`, `$2`, etc.) for parameterized inputs. The number refers to the position of the argument in the query.
-    - When a query is executed, the value passed to the `id` argument in GraphQL (via variables) will replace the `$1` marker in the SQL query.
+    - Maps the `id` argument to the `$1` marker in the SQL query, allowing dynamic ID-based retrieval.
+    - `$1` serves as a placeholder, which will be replaced by the provided `id` value during execution.
 
     **@dbquery Directive Usage**:
     - `query`: This is the SQL query that will be executed. Here, the customer data is fetched based on the provided `id` value.
@@ -61,7 +60,7 @@ type Query {
     - `type`: Specifies the type of database being queried (PostgreSQL).
     - `configuration`: References the database configuration (connection details) in StepZen.
 
-    This query requires an `id` argument as input, which is passed as a variable from the GraphQL query. The variable's value is used to fetch the corresponding customer from the database.
+    This field requires an `id` argument as input, which is passed as a variable from the GraphQL request. The variable's value is used to fetch the corresponding customer from the database.
     """
     customer(id: Int!): Customer
         @dbquery(