Connect and run your first search

Before you start

You need two things. The endpoint is your instance URL with /v1/tenants/<your-tenant>/es on the end — there is nothing to enable, every instance answers it. The API key comes from the console. The endpoint already carries your tenant, so a client treats it like any cluster URL.

export OC_ES_URL='https://<your-instance>/v1/tenants/<your-tenant>/es'
export OC_API_KEY='<your-api-key>'

The five steps

1. 1.
   Install a client

   Any Elasticsearch 7.x client works. The Node client is used here; the same requests work from Python, Java, Go, or plain curl.

   npm install @elastic/elasticsearch@7

2. 2.
   Point it at your instance

   Pass the endpoint as the node and your API key as the auth. info() clears the product check and reports the version.

   import { Client } from '@elastic/elasticsearch'
   
   const es = new Client({
     node: process.env.OC_ES_URL,
     auth: { apiKey: process.env.OC_API_KEY }
   })
   
   await es.info()   // version 7.14.2

3. 3.
   Create an index with a mapping

   Declare your fields. text is analyzed for full-text search; keyword is exact and can be grouped and sorted. Indexing explains how to choose, and what happens if you skip this step.

   await es.indices.create({
     index: 'shop.products',
     mappings: { properties: {
       name:  { type: 'text' },
       brand: { type: 'keyword' },
       price: { type: 'long' },
       added: { type: 'date' }
     } }
   })

4. 4.
   Add a document

   It is searchable the moment this returns. There is no refresh to wait for.

   await es.index({
     index: 'shop.products',
     id: 'sku-8842',
     document: {
       name: 'Carbon Marathon', brand: 'Aero',
       price: 149, added: '2026-09-01T00:00:00Z'
     }
   })

5. 5.
   Search it

   The Query DSL you already write. This one matches the analyzed text and filters on the exact brand.

   const res = await es.search({
     index: 'shop.products',
     query: { bool: {
       must:   [{ match: { name: 'marathon' } }],
       filter: [{ term:  { brand: 'Aero' } }]
     } }
   })
   
   // res.hits.total.value === 1
   // res.hits.hits[0]._source.name === 'Carbon Marathon'

Check it from the shell

The same thing without a client, so you can prove connectivity before wiring an app:

curl "$OC_ES_URL/shop.products/_search" \
  -H "Authorization: Bearer $OC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":{"match":{"name":"marathon"}}}'

Where to go next