-
Notifications
You must be signed in to change notification settings - Fork 4
feat(snippet): add example for @dbquery with SQL queries #66
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
ac58f16
feat(snippet): add example for @dbquery with SQL queries
aswanyaugustine1992 6ce966e
feat(snippet): add example for @dbquery with SQL queries
aswanyaugustine1992 f79403d
feat(snippet): add example for @dbquery with SQL queries
aswanyaugustine1992 301ebce
chore: readme updated with specific details
aswanyaugustine1992 fac6e75
chore: readme updated with specific details
aswanyaugustine1992 25089fc
fix: Enhance comments in api.graphql to clarify argument-to-variable …
aswanyaugustine1992 8f9a6f0
feat(snippet): add example for @dbquery with SQL queries
aswanyaugustine1992 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
|
||
# SQL Queries with `@dbquery` | ||
|
||
This snippet demonstrates how to configure the `@dbquery` directive for custom SQL queries. | ||
|
||
## Getting Started | ||
|
||
[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment) the StepZen command line interface. | ||
|
||
To run these examples, | ||
|
||
- `git clone` this repo | ||
- Change to the right working directory. | ||
- run `stepzen deploy` | ||
|
||
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 | ||
``` | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
# This example shows how @dbquery is configured for custom SQL queries with Customer data. | ||
|
||
""" | ||
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 | ||
} | ||
|
||
""" | ||
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. | ||
|
||
The 'customer' table in PostgreSQL has the following structure: | ||
|
||
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 | ||
); | ||
These queries demonstrate basic SQL interactions with this table. | ||
""" | ||
type Query { | ||
""" | ||
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. | ||
aswanyaugustine1992 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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. | ||
aswanyaugustine1992 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- 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. | ||
aswanyaugustine1992 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
""" | ||
customer(id: Int!): Customer | ||
@dbquery( | ||
query: "SELECT id, name, email FROM customer WHERE id = $1" | ||
type: "postgresql" | ||
configuration: "postgresql_config" | ||
) | ||
} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
configurationset: | ||
- configuration: | ||
name: postgresql_config | ||
uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. add missing newline |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
schema @sdl(files: ["api.graphql"]) { | ||
query: Query | ||
} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
# Retrieve a specific customer by ID using a variable | ||
query Customer($id: Int!) { | ||
customer(id: $id) { | ||
id | ||
name | ||
} | ||
} | ||
|
||
# Retrieve all customers in the system | ||
query Customers { | ||
customers { | ||
id | ||
name | ||
} | ||
} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
{ | ||
"endpoint": "api/miscellaneous" | ||
} | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
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 all customers", | ||
query: requests, | ||
operationName: "Customers", | ||
variables: {}, | ||
expected: { | ||
customers: [ | ||
{ id: "1", name: "Lucas Bill ", email: "[email protected] " }, | ||
aswanyaugustine1992 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
{ id: "2", name: "Mandy Jones ", email: "[email protected] " }, | ||
{ id: "3", name: "Salim Ali ", email: "[email protected] " }, | ||
{ id: "4", name: "Jane Xiu ", email: "[email protected] " }, | ||
{ id: "5", name: "John Doe ", email: "[email protected] " }, | ||
{ id: "6", name: "Jane Smith ", email: "[email protected] " }, | ||
{ id: "7", name: "Sandeep Bhushan ", email: "[email protected] " }, | ||
{ id: "8", name: "George Han ", email: "[email protected] " }, | ||
{ id: "9", name: "Asha Kumari ", email: "[email protected] " }, | ||
{ id: "10", name: "Salma Khan ", email: "[email protected] " } | ||
] | ||
}, | ||
}, | ||
{ | ||
label: "fetch customer by ID", | ||
query: requests, | ||
operationName: "Customer", | ||
variables: { | ||
aswanyaugustine1992 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
id: 1 | ||
}, | ||
expected: { | ||
customer: { | ||
id: "1", | ||
name: "Lucas Bill ", | ||
email: "[email protected] " | ||
} | ||
}, | ||
}, | ||
]; | ||
|
||
// Run the tests against the deployed schema | ||
return deployAndRun(__dirname, tests, stepzen.admin); | ||
}); |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.