dsl-builder

OpenSearch Query Builder

A library extracted from OpenSearch Dashboard for Query DSL conversion. This package provides core functionality for OpenSearch/Elasticsearch query builder.

Version Compatibility: This library is extracted from OpenSearch-Dashboards version 3.1.0 (as of 2025.7.20) and maintains compatibility with that version's query DSL structure and features.

Module Support: This package supports both CommonJS and ES Module imports for maximum compatibility.

📦 Installation

npm install dsl-builder

yarn add dsl-builder

🚀 Key Features

Query DSL Conversion

• KQL (Kibana Query Language) parsing and conversion
• Filter query creation and management
• OpenSearch/Elasticsearch query DSL generation

Field Type System

• Support for various field types (string, number, date, geo, etc.)
• Specialized query processing for each field type

Module Support

• CommonJS: const { buildOpenSearchQuery } = require('dsl-builder');
• ES Modules: import { buildOpenSearchQuery } from 'dsl-builder';

📖 Usage

KQL Query Conversion

// ES Module import
import { buildOpenSearchQuery } from 'dsl-builder';

// CommonJS import
// const { buildOpenSearchQuery } = require('dsl-builder');

const indexPattern = {
  title: 'logs-*',
  fields: [
    { name: 'status', type: 'string' },
    { name: 'response_time', type: 'number' },
    { name: '@timestamp', type: 'date' }
  ]
};

// Convert KQL query to OpenSearch DSL
const dsl = buildOpenSearchQuery(indexPattern, [
  {
    query: 'status:error AND response_time:>500',
    language: 'kuery'
  }
]);

console.log(JSON.stringify(dsl, null, 2));

🔧 API Reference

buildOpenSearchQuery

Converts query objects to OpenSearch DSL.

function buildOpenSearchQuery(
  indexPattern: IndexPattern,
  queries: Query[],
  filters: Filter[] = [],
  config: QueryState = {}
): OpenSearchQuery

📁 Project Structure

src/
├── index_patterns/          # Index pattern related functionality
│   ├── fields/             # Field types and mapping
│   ├── index_patterns/     # Index pattern service
│   ├── lib/               # Utility library
│   └── errors/            # Error handling
├── opensearch_query/       # Query DSL conversion
│   ├── kuery/             # KQL parser and converter
│   ├── filters/           # Filter processing
│   └── opensearch_query/  # Main query builder
├── query/                 # Query types and interfaces
├── osd_field_types/       # Field type system
└── utils/                 # Common utilities

🧪 Testing

# Run tests
npm test

# Test watch mode
npm run test:watch

📦 Build

# TypeScript compilation
npm run build

# Prepare for deployment
npm run prepare

🤝 Contributing

This project was extracted from the src/plugins/data/common/index_patterns module of OpenSearch Dashboard.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

🙏 Acknowledgments

This library was extracted from the OpenSearch Dashboard project. Thanks to the OpenSearch community.