Skip to content
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.

Sign up for GitHub

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

Jump to bottom

update README and other docs #24

Merged
merged 7 commits into from
Jun 20, 2024
Merged

update README and other docs #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
71f690e
add docs
pranshi06 Jun 7, 2024
5372d6a
update readme - new CLI
pranshi06 Jun 18, 2024
077000f
update readme
pranshi06 Jun 18, 2024
0367e62
update env var names
pranshi06 Jun 18, 2024
d7473ef
update instructions
pranshi06 Jun 19, 2024
09eb1d1
minor update
pranshi06 Jun 19, 2024
9afb0bb
minor update
pranshi06 Jun 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 125 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,103 +1,171 @@
# Azure Cosmos DB Connector
# Azure Cosmos Connector

The Azuer Cosmos DB connector allows you to query data present in your Azure Cosmos DB containers as NDC models
for use in your Hasura DDN subgraphs.
[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/docs/3.0/latest/connectors/azure-cosmos/)
[![ndc-hub](https://img.shields.io/badge/ndc--hub-azure--cosmos-blue.svg?style=flat)](https://hasura.io/connectors/azure-cosmos)
[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](LICENSE.txt)
[![Status](https://img.shields.io/badge/status-alpha-yellow.svg?style=flat)](./readme.md)

## Steps for building and running the connector
With this connector, Hasura allows you to instantly create a real-time GraphQL API on top of your data models in Azure Cosmos Database containers. This connector supports Azure Cosmos's functionalities listed in the table below, allowing for efficient and scalable data operations.

### Using docker
This connector is built using the [TypeScript Data Connector SDK](https://github.com/hasura/ndc-sdk-typescript) and implements the [Data Connector Spec](https://github.com/hasura/ndc-spec).

- [Connector information in the Hasura Hub](https://hasura.io/connectors/azure-cosmos)
- [Hasura V3 Documentation](https://hasura.io/docs/3.0)

## Features

### Using CLI
Below, you'll find a matrix of all supported features for the Azure Cosmos connector:

1. Make sure NodeJS v18+ is installed.
| Feature | Supported | Notes |
| ------------------------------- | --------- | ----- |
| Native Queries + Logical Models | ✅ | |
| Simple Object Query | ✅ | |
| Filter / Search | ✅ | |
| Simple Aggregation | ✅ | |
| Sort | ✅ | |
| Paginate | ✅ | |
| Nested Objects | ✅ | |
| Nested Arrays | ✅ | |
| Nested Filtering | ❌ | |
| Nested Sorting | ❌ | |
| Nested Relationships | ❌ | |

2. Run the following command to install all the required dependencies:

```sh
npm i
## Before you get Started

1. Create a [Hasura Cloud account](https://console.hasura.io)
2. Install the [CLI](https://hasura.io/docs/3.0/cli/installation/)
3. Install the [Hasura VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura)
4. [Create a supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
5. [Create a subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)

## Using the connector

To use the Azure Cosmos connector, follow these steps in a Hasura project:
(Note: for more information on the following steps, please refer to the Postgres connector documentation [here](https://hasura.io/docs/3.0/getting-started/connect-to-data/connect-a-source))


### 1. Init the connector
(Note: here and following we are naming the subgraph "my_subgraph" and the connector "my_azure_cosmos")

```bash
ddn connector init my_azure_cosmos --subgraph my_subgraph --hub-connector hasura/azure-cosmos
```

### 2. Add your Azure Cosmos credentials:

Add you credentials to `my_subgraph/connector/my_azure_cosmos/.env.local`

```env title="my_subgraph/connector/my_azure_cosmos/.env.local"
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317
OTEL_SERVICE_NAME=my_subgraph_my_azure_cosmos
AZURE_COSMOS_DB_NAME= <YOUR_AZURE_DB_NAME>
AZURE_COSMOS_ENDPOINT= <YOUR_AZURE_COSMOS_ENDPOINT>
AZURE_COSMOS_KEY= <YOUR_AZURE_COSMOS_KEY>
AZURE_COSMOS_NO_OF_ROWS_TO_FETCH= <NO-OF-ROWS-TO-FETCH>
```

3. To build the connector,
Note: `AZURE_COSMOS_CONNECTOR_NO_OF_ROWS_TO_FETCH` is an optional field, with 100 rows to be fetched by default.

### 3. Intropsect your indices

```sh
npm run build
From the root of your project run:

```bash title="From the root of your project run:"
ddn connector introspect --connector my_subgraph/connector/my_azure_cosmos/connector.yaml
```

4. Set the following environment variables:
If you look at the `config.json` for your connector, you'll see metadata describing your Azure Cosmos mappings.

### 4. Create the Hasura metadata

Run the following from the root of your project:

```sh
export AZURE_COSMOS_ENDPOINT=<YOUR_AZURE_COSMOS_ENDPOINT>
export AZURE_COSMOS_KEY=<YOUR_AZURE_COSMOS_KEY>
export AZURE_COSMOS_DB_NAME=<YOUR_AZURE_DB_NAME>
```bash title="Run the following from the root of your project:"
ddn connector-link add my_azure_cosmos --subgraph my_subgraph
```

5. Generate the configuration required to run the connector:
The generated file has two environment variables — one for reads and one for writes — that you'll need to add to your
subgraph's `.env.my_subgraph` file. Each key is prefixed by the subgraph name, an underscore, and the name of the
connector. Ensure the port value matches what is published in your connector's docker compose file.

```sh
npm install -g
ndc-azure-cosmos update
```env title="my_subgraph/.env.my_subgraph"
MY_SUBGRAPH_MY_AZURE_COSMOS_READ_URL=http://local.hasura.dev:8081
MY_SUBGRAPH_MY_AZURE_COSMOS_WRITE_URL=http://local.hasura.dev:8081
```

This will generate a `config.json` file in the root directory, by default. The
location of this file can be configured by providing the `--output-directory` command.
### 5. Start the connector's docker compose

4. To start the connector,
Let's start our connector's docker compose file. Run the following from the connector's subdirectory inside a subgraph:

```sh
npm run start serve -- --configuration .
```bash title="Run the following from the connector's subdirectory inside a subgraph:"
docker compose -f docker-compose.my_azure_cosmos.yaml up
```

The `--configuration` directory should contain the configuration file generated in the previous step.
This starts our Azure Cosmos connector on the specified port. We can navigate to the following address, with the port
modified, to see the schema of our Azure Cosmos data source:

Alternatively, to use a local Azure Cosmos emulator, start the connector with the following command,

```sh
npm run start serve -- --configuration connector_config_emulator.json
```bash
http://localhost:8081/schema
```

The emulator can be setup by following [this](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-develop-emulator?pivots=api-nosql&tabs=windows%2Ccsharp) link.
### 6. Include the connector in your docker compose

Kill the connector by pressing `CTRL+C` in the terminal tab in which the connector is running.

## Steps to test the connector (ndc-test via emulator)
Then, add the following inclusion to the docker compose `docker-compose.hasura.yaml` in your project's root directory, taking care to modify the
subgraph's name.

1. Make sure that the Azure Cosmos emulator is up and running.
```yaml title="docker-compose.hasura.yaml"
include:
- path: my_subgraph/connector/my_azure_cosmos/docker-compose.my_azure_cosmos.yaml
```

2. Create a database contaner and upload data into the emulator,
Now, whenever running the following, you'll bring up the GraphQL engine, observability tools, and any connectors you've
included. From the root of your project, run:

```sh
cd script
npm i
node app.js
```bash title="From the root of your project, run:"
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose -f docker-compose.hasura.yaml watch
```

3. Start the connector using,
### 7. Update the new DataConnectorLink object

Finally, now that our `DataConnectorLink` has the correct environment variables configured for the Azure Cosmos connector,
we can run the update command to have the CLI look at the configuration JSON and transform it to reflect our database's
schema in `hml` format. In a new terminal tab from the root of your project, run:

```sh
npm run build
npm run start serve -- --configuration connector_config_emulator.json
```bash title="From the root of your project, run:"
ddn connector-link update my_azure_cosmos --subgraph my_subgraph
```

4. Checkout to the [ndc-spec repository](https://github.com/hasura/ndc-spec) and run
After this command runs, you can open your `my_subgraph/metadata/my_azure_cosmos.hml` file and see your metadata completely
scaffolded out for you 🎉

### 8. Import _all_ your indices

```sh
cargo run --bin ndc-test -- replay --endpoint http://localhost:8080 --snapshots-dir ../ndc-azure-cosmos-connector/ndc-test-snapshots --no-validate-responses
You can do this in one convenience command. From the root of your project, run:

```bash title="From the root of your project, run:"
ddn connector-link update my_azure_cosmos --subgraph my_subgraph --add-all-resources
```

Note:
### 9. Create a supergraph build

1. The `snapshot-dir` is the relative path from the ndc-spec repository to the `ndc-test-snapshots` folder in the `ndc-azure-cosmos-connector` repository.
Pass the `local` subcommand along with specifying the output directory as `./engine` in the root of the project. This
directory is used by the docker-compose file to serve the engine locally. From the root of your project, run:

2. `--endpoint` is the URL at which the connector is running.
```bash title="From the root of your project, run:"
ddn supergraph build local --output-dir ./engine
```

You can now navigate to
[`https://console.hasura.io/local/graphql?url=http://localhost:3000`](https://console.hasura.io/local/graphql?url=http://localhost:3000)
and interact with your API using the Hasura Console.

## Types supported
## Contributing

### Scalar types
We're happy to receive any contributions from the community. Please refer to our [development guide](./docs/development.md).

Currently, the following scalar types are supported:
## License

1. `Integer`
2. `Number`
3. `String`
4. `Boolean`
The Hasura Azure Cosmos connector is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
60 changes: 60 additions & 0 deletions docs/code-of-conduct.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Hasura GraphQL Engine Community Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make
participation in our project and our community a harassment-free experience for everyone, regardless of age, body size,
disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education,
socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment include:

* Using welcoming, inclusive and gender-neutral language (example: instead of "Hey guys", you could use "Hey folks" or
"Hey all")
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take
appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the
project or its community. Examples of representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed representative at an online or offline
event. Representation of a project may be further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at
[email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed
necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to
the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent
repercussions as determined by other members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org
39 changes: 39 additions & 0 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Contributing

_First_: if you feel insecure about how to start contributing, feel free to ask us on our
[Discord channel](https://discordapp.com/invite/hasura) in the #contrib channel. You can also just go ahead with your contribution and we'll give you feedback. Don't worry - the worst that can happen is that you'll be politely asked to change something. We appreciate any contributions, and we don't want a wall of rules to stand in the way of that.

However, for those individuals who want a bit more guidance on the best way to contribute to the project, read on. This document will cover what we're looking for. By addressing the points below, the chances that we can quickly merge or address your contributions will increase.

## 1. Code of conduct

Please follow our [Code of conduct](./code-of-conduct.md) in the context of any contributions made to Hasura.

## 2. CLA

For all contributions, a CLA (Contributor License Agreement) needs to be signed
[here](https://cla-assistant.io/hasura/ndc-sqlserver) before (or after) the pull request has been submitted. A bot will prompt contributors to sign the CLA via a pull request comment, if necessary.

## 3. Ways of contributing

### Reporting an Issue

- Make sure you test against the latest released cloud version. It is possible that we may have already fixed the bug you're experiencing.
- Provide steps to reproduce the issue, including Database (e.g. SQL Server) version and Hasura DDN version.
- Please include logs, if relevant.
- Create a [issue](https://github.com/hasura/ndc-sqlserver/issues/new/choose).

### Working on an issue

- We use the [fork-and-branch git workflow](https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/).
- Please make sure there is an issue associated with the work that you're doing.
- If you're working on an issue, please comment that you are doing so to prevent duplicate work by others also.
- Squash your commits and refer to the issue using `fix #<issue-no>` or `close #<issue-no>` in the commit message, at the end. For example: `resolve answers to everything (fix #42)` or `resolve answers to everything, fix #42`
- Rebase master with your branch before submitting a pull request.

## 6. Commit messages

- The first line should be a summary of the changes, not exceeding 50 characters, followed by an optional body which has more details about the changes. Refer to [this link](https://github.com/erlang/otp/wiki/writing-good-commit-messages) for more information on writing good commit messages.
- Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes".
- Don't capitalize the first letter of the summary line.
- Don't add a period/dot (.) at the end of the summary line.
Loading
Loading