> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Elasticsearch

> Connect to Elasticsearch indices with query and aggregation support

<Note>Only available for Node.js.</Note>

The Elasticsearch datasource connects to Elasticsearch indices, allowing you to query, filter, and aggregate your data through Forest.

## Basic usage

```javascript theme={null}
import { createAgent } from '@forestadmin/agent';
import { createElasticsearchDataSource } from '@forestadmin-experimental/datasource-elasticsearch';

const agent = createAgent(options);

agent.addDataSource(
  createElasticsearchDataSource({
    node: 'http://localhost:9200',
    auth: {
      username: 'elastic',
      password: 'your-password'
    }
  })
);
```

## Configuration options

### Index-based collections

Map each Elasticsearch index to a Forest collection:

```javascript theme={null}
createElasticsearchDataSource({
  node: 'http://localhost:9200',
  indices: [
    {
      name: 'products',
      fields: {
        id: { type: 'Number' },
        name: { type: 'String' },
        price: { type: 'Number' },
        category: { type: 'String' },
        tags: { type: 'StringList' },
        created_at: { type: 'Date' }
      }
    }
  ]
})
```

### Template-based collections

Use Elasticsearch index templates to automatically generate collections:

```javascript theme={null}
createElasticsearchDataSource({
  node: 'http://localhost:9200',
  templates: [
    {
      name: 'logs-*',
      fields: {
        timestamp: { type: 'Date' },
        level: { type: 'String' },
        message: { type: 'String' }
      }
    }
  ]
})
```

### Authentication

The datasource supports multiple authentication methods:

```javascript theme={null}
// Basic authentication
createElasticsearchDataSource({
  node: 'https://elastic.example.com:9200',
  auth: {
    username: 'elastic',
    password: 'password'
  }
})

// API key authentication
createElasticsearchDataSource({
  node: 'https://elastic.example.com:9200',
  auth: {
    apiKey: 'your-api-key'
  }
})

// Bearer token
createElasticsearchDataSource({
  node: 'https://elastic.example.com:9200',
  auth: {
    bearer: 'your-bearer-token'
  }
})
```

### SSL/TLS configuration

```javascript theme={null}
createElasticsearchDataSource({
  node: 'https://elastic.example.com:9200',
  tls: {
    ca: fs.readFileSync('./ca.crt'),
    rejectUnauthorized: true
  }
})
```

## Field types

The datasource supports the following field types:

* `String` - Text fields
* `Number` - Numeric fields
* `Boolean` - Boolean fields
* `Date` - Date/datetime fields
* `StringList` - Array of strings
* `Json` - Nested objects (stored as JSON)

Arrays must be explicitly specified using the `List` suffix (e.g., `StringList`).

## Query capabilities

### Filtering

The datasource supports 16+ filter operators:

* `Equal`, `NotEqual`
* `GreaterThan`, `LessThan`
* `In`, `NotIn`
* `Contains`, `StartsWith`, `EndsWith`
* `Present`, `Blank`
* `Match` (full-text search)
* And more

### Sorting

Sort records by any field:

```javascript theme={null}
// Forest UI automatically generates queries with sorting
// Example: GET /products?sort=-price (descending by price)
```

### Aggregations

The datasource supports Elasticsearch aggregations for charts and analytics:

* Count
* Sum
* Average
* Min/Max
* Terms aggregation (group by)

### Native SQL queries

Execute Elasticsearch SQL queries directly:

```javascript theme={null}
agent.customizeCollection('products', collection => {
  collection.addAction('Run SQL Query', {
    scope: 'Global',
    execute: async (context) => {
      const result = await context.dataSource.executeNativeQuery(
        'SELECT category, AVG(price) FROM products GROUP BY category'
      );
      return result;
    }
  });
});
```

## Live Query

This datasource supports Live Query for advanced filtering and segmentation. [Learn more about Live Queries](/product/process/segments/smart-segments/overview)

## Limitations

* **No joins** - Relationships between indices are not supported
* **No object sub-models** - Nested objects are flattened to JSON fields
* **No geospatial types** - Point fields are not supported
* **Array specification** - Arrays must be manually specified with `List` suffix
* **Read-heavy** - Optimized for search and analytics, not transactional workloads

## Elasticsearch 8.x support

This datasource is built for Elasticsearch 8.x and uses the official `@elastic/elasticsearch` client. It supports:

* Index templates
* Data streams
* Modern query DSL
* SQL API
* Security features (authentication, TLS)

## Source code

This connector is open source. Browse the code or contribute on GitHub: [`@forestadmin-experimental/datasource-elasticsearch`](https://github.com/ForestAdmin/forestadmin-experimental/tree/main/packages/datasource-elasticsearch).