GraphQL Data Connector docs

spiceaidocs/docs/data-connectors/graphql.md

@@ -0,0 +1,106 @@
+---
+title: 'GraphQL Data Connector'
+sidebar_label: 'GraphQL Data Connector'
+description: 'GraphQL Data Connector Documentation'
+---
+
+## Federated SQL query
+
+To connect to any [GraphQL](https://graphql.org/) endpoint as connector for federated SQL query, specify `graphql` as the selector in the `from` value for the dataset.
+
+```yaml
+datasets:
+  - from: graphql:your-graphql-endpoint
+    name: my_dataset
+    params:
+      json_path: data.some.nodes
+      query: |
+        {
+          some {
+            nodes {
+              field1
+              field2
+            }
+          }
+        }
+```
+
+## Limitations
+
+- The GraphQL data connector does not support pagination.
+- The GraphQL data connector does not support variables in the query.
+- Acceleration only works with `arrow` engine. Support for other engines is in progress.
+- You need to specify path to an object or array (preferably array) in the JSON response using `json_path` parameter. More fine grained access will be supported in future.
+
+## Configuration
+
+The GraphQL data connector can be configured by providing the following `params`:
+
+- `auth_token`: The authentication token to use to connect to the GraphQL server. Uses bearer authentication. E.g. `auth_token: github_pat_...`
+- `auth_token_key`: The secret key containing the authentication token to use to connect to the GraphQL server. Can be used instead of `auth_token`.
+E.g. `auth_token_key: github_token`
+- `auth_user`: The username to use for basic auth. E.g. `auth_user: my_user`
+- `auth_user_key`: The secret key containing the user to use for basic auth. Can be used instead of `auth_user`. E.g. `auth_user_key: my_secret_user`
+- `auth_pass`: The password to use for basic auth. E.g. `auth_pass: my_password`
+- `auth_pass_key`: The secret key containing the password to use for basic auth. Can be used instead of `auth_pass`. E.g. `auth_pass_key: my_secret_password`
+- `query`: The GraphQL query to execute. E.g.
+```yaml
+query: |
+  {
+    some {
+      nodes {
+        field1
+        field2
+      }
+    }
+  }
+```
+- `json_path`: The path to the JSON data in the response. E.g. `json_path: data.some.nodes`
+
+Configuration `params` are provided either in the top level `dataset` for a dataset source and federated SQL query.
+
+Example using github graphql API using Bearer Auth:
+```yaml
+from: graphql:https://api.github.com/graphql
+name: stars
+params:
+  auth_token: [your_github_token>]
+  json_path: data.viewer.starredRepositories.nodes
+  query: |
+    {
+      viewer {
+        starredRepositories {
+          nodes {
+            name
+            stargazerCount
+            languages (first: 10) {
+              nodes {
+                name
+              }
+            }
+          }
+        }
+      }
+    }
+
+```
+You can query nested structures as well. Here is an example of querying a nested structure:
+<img width="500" src="/img/graphql/stars-query.png" />
+
+Example using Basic Auth:
+```yaml
+from: graphql:https://your-site.com/graphql
+name: your_dataset
+params:
+  auth_user: [your_user]
+  auth_pass: [your_password]
+  query: |
+    {
+      some {
+        nodes {
+          field1
+          field2
+        }
+      }
+    }
+```

spiceaidocs/docs/data-connectors/index.md

@@ -24,6 +24,7 @@ Currently supported Data Connectors include:
 | `clickhouse` | Clickhouse  | Alpha        |                                     | `full`           | ❌               |
 | `spark`      | Spark       | Alpha        | Spark Connect                       | `full`           | ❌               |
 | `ftp`, `sftp`| FTP/SFTP    | Alpha        | Parquet, CSV                        | `full`           | ❌               |
+| `graphql`    | GraphQL     | Alpha         | GraphQL                               | `full`           | ❌               |
 
 ## Data Connector Docs
 

spiceaidocs/docs/reference/spicepod/datasets.md

@@ -84,6 +84,7 @@ Where:
   - [`postgres`](../../data-connectors/postgres/index.md)
   - [`mysql`](../../data-connectors/mysql.md)
   - [`clickhouse`](../../data-connectors/clickhouse.md)
+  - [`graphql`](../../data-connectors/graphql.md)
 
   If the Data Connector is not explicitly specified, it defaults to `spiceai`.