OpenSearch is a community-driven search and analytics suite with strong BM25 full-text search and k-NN approximate nearest neighbor search via the k-NN plugin. Gateco connects to OpenSearch as a Tier 2 connector, supporting vector, keyword, hybrid, and grep search — adding identity-aware retrieval and RAG access control policies on top of your existing indexes.
Step 1 — Verify the k-NN plugin
curl -s -u admin:admin http://localhost:9200/_cat/plugins?v | grep knnYou should see a row for opensearch-knn. If not, install OpenSearch 2.9+ from opensearch.org — the k-NN plugin is included.
Step 2 — Create an index with a knn_vector field
curl -s -u admin:admin -XPUT http://localhost:9200/my-docs \
-H 'Content-Type: application/json' -d '
{
"settings": { "index.knn": true },
"mappings": {
"properties": {
"embedding": {
"type": "knn_vector",
"dimension": 1536,
"method": { "name": "hnsw", "space_type": "cosinesimil", "engine": "lucene" }
},
"content": { "type": "text" },
"doc_id": { "type": "keyword" }
}
}
}'Use space_type: "cosinesimil" for cosine similarity (recommended for semantic search). Use "l2" for Euclidean distance. The engine can be "lucene", "nmslib", or "faiss" — "lucene" is available on all OpenSearch distributions.
Step 3 — Add the connector in Gateco
- Navigate to Connectors → Add connector → OpenSearch.
- Enter your OpenSearch endpoint URL.
- Enter username and password (or leave blank if security plugin is disabled).
- Click Test connection.
- Click Save.
| Field | Example | Description |
|---|---|---|
url | https://search-my-domain.us-east-1.es.amazonaws.com | OpenSearch cluster endpoint |
index_name | my-docs | Index containing vector embeddings |
vector_field | embedding | Field with type knn_vector |
content_field | content | Text field for keyword/hybrid/grep search |
username | admin | OpenSearch username (leave blank if security disabled) |
password | your-password | OpenSearch password |
Step 4 — Configure search settings
After saving the connector, configure search settings:
- Click your OpenSearch connector → Search config.
- Set the Index name, Vector field, and Content field.
- For hybrid search, the default alpha of 0.5 provides equal vector and keyword weight.
- Save.
OpenSearch supports substring and regex grep search. Patterns are validated server-side (max 200 chars, no nested quantifiers). Regex grep uses OpenSearch Lucene regex syntax.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
index_not_found_exception | Wrong index name | Check the exact index name in OpenSearch Dashboard → Index Management |
mapper_parsing_exception: knn_vector | k-NN plugin not active | Run GET /_cat/plugins and verify opensearch-knn is installed |
security_exception: 403 | User lacks index permissions | Grant index-level indices:data/read/* permissions to the OpenSearch user |