From 5eda2128fcbe710741f07a404a6eb69214da2731 Mon Sep 17 00:00:00 2001 From: Tristen Harr Date: Thu, 22 Aug 2024 12:11:20 -0500 Subject: [PATCH] update docs --- CHANGELOG.md | 3 + README.md | 115 +++++-------------- connector-definition/connector-metadata.yaml | 4 +- docs/development.md | 27 ++--- docs/support.md | 2 +- package-lock.json | 4 +- package.json | 2 +- 7 files changed, 47 insertions(+), 110 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 04e14db..6c21600 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Qdrant Connector Changelog This changelog documents changes between release tags. +## [0.3.0] - 2024-08-22 +* Update Documentation for ndc-hub + ## [0.2.6] - 2024-08-13 * Fix workflow to publish to NDC-hub diff --git a/README.md b/README.md index 2e1a7bb..02fa25c 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ The Hasura Qdrant Connector allows for connecting to a Qdrant database to give y 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/qdrant) -* [Hasura V3 Documentation](https://hasura.io/docs/3.0/index/) +- [See the listing in the Hasura Hub](https://hasura.io/connectors/qdrant) +- [Hasura V3 Documentation](https://hasura.io/docs/3.0/index/) ## Features @@ -52,113 +52,60 @@ connector — after it's been configured — [here](https://hasura.io/docs/3.0/g ddn auth login ``` -### Step 2: Initialize the connector +### Step 2: Configure the connector -```bash -ddn connector init qdrant --subgraph my_subgraph --hub-connector hasura/qdrant -``` - -In the snippet above, we've used the subgraph `my_subgraph` as an example; however, you should change this -value to match any subgraph which you've created in your project. - -### Step 3: Modify the connector's port - -When you initialized your connector, the CLI generated a set of configuration files, including a Docker Compose file for -the connector. Typically, connectors default to port `8080`. Each time you add a connector, we recommend incrementing the published port by one to avoid port collisions. - -As an example, if your connector's configuration is in `my_subgraph/connector/qdrant/docker-compose.qdrant.yaml`, you can modify the published port to reflect a value that isn't currently being used by any other connectors: - -```yaml -ports: - - mode: ingress - target: 8080 - published: "8082" - protocol: tcp -``` - -### Step 4: Add environment variables - -Now that our connector has been scaffolded out for us, we need to provide a connection string so that the data source can be introspected and the boilerplate configuration can be taken care of by the CLI. - -The CLI has provided an `.env.local` file for our connector in the `my_subgraph/connector/qdrant` directory. We can add a key-value pair of `QDRANT_URL` along with the connection string itself to this file, and our connector will use this to connect to our database. If the Qdrant database has an API key you can also provide the environment variable for the `QDRANT_API_KEY` which allows the connector to authenticate. - - -The file, after adding the `QDRANT_URL`, should look like this example if connecting to a Qdrant hosted database instance: - -```env -OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317 -OTEL_SERVICE_NAME=my_subgraph_qdrant -QDRANT_URL=https://7312d6c4-3f6c-432c-987c-34d7d96428ef.us-east4-0.gcp.cloud.qdrant.io -QDRANT_API_KEY=Ch8I... -``` - -To connect to a locally running Qdrant instance you can then point the `QDRANT_URL` to the local database. Assuming the Qdrant database is running on port 6333 without any API key, you should be able to use this example: - -```env -OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://local.hasura.dev:4317 -OTEL_SERVICE_NAME=my_subgraph_qdrant -QDRANT_URL=http://local.hasura.dev:6333 -``` - -### Step 5: Introspect your data source - -With the connector configured, we can now use the CLI to introspect our database and create a source-specific configuration file for our connector. +Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while providing a name for the connector in the prompt: ```bash -ddn connector introspect --connector my_subgraph/connector/qdrant/connector.local.yaml +ddn connector init qdrant -i ``` -### Step 6. Create the Hasura metadata +#### Step 2.1: Choose the `hasura/qdrant` option from the list -Hasura DDN uses a concept called "connector linking" to take [NDC-compliant](https://github.com/hasura/ndc-spec) -configuration JSON files for a data connector and transform them into an `hml` (Hasura Metadata Language) file as a -[`DataConnectorLink` metadata object](https://hasura.io/docs/3.0/supergraph-modeling/data-connectors#dataconnectorlink-dataconnectorlink). +#### Step 2.2: Choose a port for the connector -Basically, metadata objects in `hml` files define our API. +The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the default suggested port. -First we need to create this `hml` file with the `connector-link add` command and then convert our configuration files -into `hml` syntax and add it to this file with the `connector-link update` command. +#### Step 2.3: Provide the env var(s) for the connector -Let's name the `hml` file the same as our connector, `qdrant`: +| Name | Description | +|-|-| +| QDRANT_URL | The connection string for the Qdrant database | +| QDRANT_API_KEY | The Qdrant API Key | -```bash -ddn connector-link add qdrant --subgraph my_subgraph -``` - -The new file is scaffolded out at `my_subgraph/metadata/qdrant/qdrant.hml`. - -### Step 7. Update the environment variables +You'll find the environment variables in the `.env` file and they will be in the format: -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. +`__` -As an example: +Here is an example of what your `.env` file might look like: -```env -MY_SUBGRAPH_QDRANT_READ_URL=http://local.hasura.dev: -MY_SUBGRAPH_QDRANT_WRITE_URL=http://local.hasura.dev: +``` +APP_QDRANT_AUTHORIZATION_HEADER="Bearer B9-PceSL1QrUE_Z1gJNdGQ==" +APP_QDRANT_HASURA_SERVICE_TOKEN_SECRET="B9-PceSL1QrUE_Z1gJNdGQ==" +APP_QDRANT_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://local.hasura.dev:4317" +APP_QDRANT_OTEL_SERVICE_NAME="app_qdrant" +APP_QDRANT_QDRANT_API_KEY="5PX..." +APP_QDRANT_QDRANT_URL="https://2a4ae326-fdef-473e-a13c-7dc07f2f2759.us-east4-0.gcp.cloud.qdrant.io" +APP_QDRANT_READ_URL="http://local.hasura.dev:5963" +APP_QDRANT_WRITE_URL="http://local.hasura.dev:5963" ``` -These values are for the connector itself and utilize `local.hasura.dev` to ensure proper resolution within the docker container. - -### Step 8. Start the connector's Docker Compose +### Step 3: Introspect the connector -Let's start our connector's Docker Compose file by running the following from inside the connector's subgraph: +Introspecting the connector will generate a `config.json` file and a `qdrant.hml` file. ```bash -docker compose -f docker-compose.qdrant.yaml up +ddn connector introspect qdrant ``` -### Step 9. Update the new `DataConnectorLink` object +### Step 4: Add your resources -Finally, now that our `DataConnectorLink` has the correct environment variables configured for the 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, run: +You can add the models, commands, and relationships to your API by tracking them which generates the HML files. ```bash -ddn connector-link update qdrant --subgraph my_subgraph +ddn connector-link add-resources qdrant ``` -After this command runs, you can open your `my_subgraph/metadata/qdrant.hml` file and see your metadata completely -scaffolded out for you 🎉 - ## Documentation View the full documentation for the Qdrant connector [here](https://github.com/hasura/ndc-qdrant/blob/main/docs/index.md). diff --git a/connector-definition/connector-metadata.yaml b/connector-definition/connector-metadata.yaml index 7a13492..1655cf3 100644 --- a/connector-definition/connector-metadata.yaml +++ b/connector-definition/connector-metadata.yaml @@ -1,6 +1,6 @@ packagingDefinition: type: PrebuiltDockerImage - dockerImage: ghcr.io/hasura/ndc-qdrant:v0.2.6 + dockerImage: ghcr.io/hasura/ndc-qdrant:v0.3.0 supportedEnvironmentVariables: - name: QDRANT_URL description: The url for the Qdrant database @@ -9,7 +9,7 @@ supportedEnvironmentVariables: commands: update: type: Dockerized - dockerImage: ghcr.io/hasura/ndc-qdrant:v0.2.6 + dockerImage: ghcr.io/hasura/ndc-qdrant:v0.3.0 commandArgs: - update dockerComposeWatch: diff --git a/docs/development.md b/docs/development.md index 3e1be28..5a4ab27 100644 --- a/docs/development.md +++ b/docs/development.md @@ -25,36 +25,23 @@ To start the connector on port 9094, for a Qdranto hosted database instance run: ### Attach the connector to the locally running engine -There should a file located at `my_subgraph/.env.my_subgraph` that contains +There should a file located at `.env` that contains ```env -MY_SUBGRAPH_QDRANT_READ_URL=http://local.hasura.dev: -MY_SUBGRAPH_QDRANT_WRITE_URL=http://local.hasura.dev: +APP_QDRANT_READ_URL="http://local.hasura.dev:" +APP_QDRANT_WRITE_URL="http://local.hasura.dev:" ``` -Create a new .env file called `.env.my_subgraph.dev` and place the following values into it: +Edit the values in the `.env` file to point at port 9094 with the locally running connector. ```env -MY_SUBGRAPH_QDRANT_READ_URL=http://local.hasura.dev:9094 -MY_SUBGRAPH_QDRANT_WRITE_URL=http://local.hasura.dev:9094 -``` - -In your `supergraph.yaml` file change the env file to point to the dev file. - -``` - subgraphs: - my_subgraph: - generator: - rootPath: my_subgraph - # envFile: my_subgraph/.env.my_subgraph # Change the env file - envFile: my_subgraph/.env.my_subgraph.dev - includePaths: - - my_subgraph/metadata +APP_QDRANT_READ_URL="http://local.hasura.dev:9094" +APP_QDRANT_WRITE_URL="http://local.hasura.dev:9094" ``` Do a local supergraph build: -```ddn supergraph build local --output-dir ./engine``` +```ddn supergraph build local``` Mutations and Queries will now be issued against your locally running connector instance. diff --git a/docs/support.md b/docs/support.md index f814927..047e933 100644 --- a/docs/support.md +++ b/docs/support.md @@ -2,7 +2,7 @@ The documentation and community will help you troubleshoot most issues. If you have encountered a bug or need to get in touch with us, you can contact us using one of the following channels: * Support & feedback: [Discord](https://discord.gg/hasura) -* Issue & bug tracking: [GitHub issues](https://github.com/hasura/ndc=[connectorName]/issues) +* Issue & bug tracking: [GitHub issues](https://github.com/hasura/ndc-qdrant/issues) * Follow product updates: [@HasuraHQ](https://twitter.com/hasurahq) * Talk to us on our [website chat](https://hasura.io) diff --git a/package-lock.json b/package-lock.json index d826a16..aa94fe9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "ndc-qdrant", - "version": "0.2.6", + "version": "0.3.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "ndc-qdrant", - "version": "0.2.6", + "version": "0.3.0", "dependencies": { "@hasura/ndc-sdk-typescript": "^6.0.0", "@qdrant/js-client-rest": "^1.5.0" diff --git a/package.json b/package.json index d38fd24..dc4462f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ndc-qdrant", - "version": "0.2.6", + "version": "0.3.0", "main": "index.js", "scripts": { "start": "ts-node ./src/index.ts serve --configuration=.",