Skip to content

remove ddn cli steps from readme #61

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

Merged
merged 1 commit into from
Feb 13, 2025
Merged

remove ddn cli steps from readme #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
117 changes: 36 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This connector is built using the [Go Data Connector SDK](https://github.com/has

- [See the listing in the Hasura Hub](https://hasura.io/connectors/elasticsearch)
- [Hasura DDN Documentation](https://hasura.io/docs/3.0)
- [Hasura DDN Quickstart](https://hasura.io/docs/3.0/getting-started/quickstart)
- [Hasura DDN Quickstart with Elasticsearch](https://hasura.io/docs/3.0/how-to-build-with-ddn/with-elasticsearch)
- [GraphQL on Elasticsearch](https://hasura.io/graphql/database/elasticsearch)

Docs for the Elasticsearch data connector:
Expand All @@ -29,86 +29,41 @@ Docs for the Elasticsearch data connector:

Below, you'll find a matrix of all supported features for the Elasticsearch connector:

| Feature | Supported | Notes |
| ------------------------------- | --------- | ----- |
| Native Queries + Logical Models | ❌ | |
| Simple Object Query | ✅ | |
| Filter / Search | ✅ | |
| Simple Aggregation | alpha\* | |
| Sort | ✅ | |
| Paginate | ✅ | |
| Relationships | ✅\* | |
| Nested Objects | ✅ | |
| Nested Arrays | ✅ | |
| Nested Filtering | ✅ | |
| Nested Sorting | ❌ | |
| Nested Relationships | ❌ | |

> [!Note]
> - **Relationships** are currently implemented via `top_hits` operator. That operator has a default maximum result size limit of 100 rows. This is what the connector operates on. If you give the connector a higher limit, it will change that to 100 for compliance with the database. Also, since the returned result will contain only 100 rows per bucket, it may not represent the whole result.

> [!Note]
> Aggregations are currently in alpha and are being actively worked upon

## Before you get Started

1. Create a [Hasura Cloud account](https://console.hasura.io)
2. Please ensure you have the [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/) installed
3. [Create a supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
4. [Create a subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)

## Using the Elasticsearch connector

### Step 1: Authenticate your CLI session

```bash
ddn auth login
```

### Step 2: Configure the 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 init <connector-name> -i
```

#### Step 2.1: Choose `hasura/elasticsearch` from the list

#### Step 2.2: Choose a port for the connector

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.

#### Step 2.3: Provide the env vars required for the connector

To configure the connector, the following environment variables need to be set:

| Environment Variable | Description | Required | Example Value |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `ELASTICSEARCH_URL` | The comma-separated list of Elasticsearch host addresses for connection (Use `local.hasura.dev` instead of `localhost` if your connector is running on your local machine) | Yes | `https://example.es.gcp.cloud.es.io:9200` |
| `ELASTICSEARCH_USERNAME` | The username for authenticating to the Elasticsearch cluster | Yes | `admin` |
| `ELASTICSEARCH_PASSWORD` | The password for the Elasticsearch user account | Yes | `default` |
| `ELASTICSEARCH_API_KEY` | The Elasticsearch API key for authenticating to the Elasticsearch cluster | No | `ABCzYWk0NEI0aDRxxxxxxxxxx1k6LWVQa2gxMUpRTUstbjNwTFIzbGoyUQ==` |
| `ELASTICSEARCH_CA_CERT_PATH` | The path to the Certificate Authority (CA) certificate for verifying the Elasticsearch server's SSL certificate | No | `/etc/connector/cacert.pem` |
| `ELASTICSEARCH_INDEX_PATTERN` | The pattern for matching Elasticsearch indices, potentially including wildcards, used by the connector | No | `hasura*` |

## Step 3: Introspect the connector

```bash
ddn connector introspect <connector-name>
```

This will generate a `configuration.json` file that will have the schema of your Elasticsearch DB.

## Step 4: Add your resources

```bash
ddn connector-link add-resources <connector-name>
```

This command will track all the indices in your Elasticsearch DB as [Models](https://hasura.io/docs/3.0/supergraph-modeling/models).
| Feature | Supported |
| --------------------------------------- | --------- |
| Native Queries | ❌ |
| Native Mutations | ❌ |
| Filter / Search via term | ✅ |
| Filter / Search via terms | ✅ |
| Filter / Search via match | ✅ |
| Filter / Search via match_bool_prefix | ✅ |
| Filter / Search via match_phrase | ✅ |
| Filter / Search via prefix | ✅ |
| Filter / Search via range | ✅ |
| Filter / Search via regexp | ✅ |
| Filter / Search via wildcard | ✅ |
| Filter / Search via terms_set | ❌ |
| Filter / Search via intervals | ❌ |
| Filter / Search via query_string | ❌ |
| Filter / Search via simple_query_string | ❌ |
| Filter / Search via fuzzy | ❌ |
| Simple Aggregation | ✅ |
| Sort | ✅ |
| Paginate via offset | ✅ |
| Paginate via search_after | ✅ |
| Distinct | ❌ |
| Enums | ❌ |
| Default Values | ✅ |
| User-defined Functions | ❌ |
| Index Aliases | ✅ |
| Field Aliases | ❌ |
| Multi Fields | ❌ |
| Runtime Fields | ❌ |
| Field Analyzers | ❌ |

## Getting Started

Please see [Getting Started with Elasticsearch on Hasura DDN](https://hasura.io/docs/3.0/how-to-build-with-ddn/with-elasticsearch) to instantly get a GraphQL API on Elasticsearch by connecting it to Hasura DDN.

## Detailed Documentation

Expand Down