PPL overview
LynxDB queries are written in OpenSearch Piped Processing Language (PPL). A
query is a pipeline: a source command reads events, and each command after a
| transforms the rows the previous command produced.
source=main status>=500 earliest=-1h
| stats count() as errors, p95(response_time) as p95 by host
| sort - errors
| head 5
The same text runs everywhere a query is accepted:
| Entry point | What runs the query |
|---|---|
lynxdb query '<query>' | the server, over REST |
lynxdb query --file app.log '<query>', cat app.log | lynxdb query '<query>' | the CLI process, over the input loaded into the index main |
POST /api/v1/query, /api/v1/query/stream | the server |
lynxdb explain '<query>', GET /api/v1/query/explain | the server's compiler, without running the query |
Every entry point compiles the text with the same compiler (pkg/query) into
the same plan, so a query that works on a file works on the server.
How LynxDB relates to OpenSearch PPL
The PPL pages keep three things apart:
- OpenSearch PPL semantics. Syntax, commands, functions and their documented behavior follow the OpenSearch PPL reference. Where LynxDB implements a feature fully, the OpenSearch documentation applies.
- LynxDB execution behavior. LynxDB stores schema-on-read log events, not OpenSearch documents. Free-text search matches the tokens of every string field of an event, every index is local, and there are no relevance scores. Where this changes a result, the pages say so under a LynxDB behavior heading.
- OpenSearch features LynxDB does not support. Unsupported commands,
functions and options fail at compile time with an
UNSUPPORTED_COMMAND,UNSUPPORTED_FUNCTIONorUNSUPPORTED_FEATUREerror. Nothing unsupported is silently approximated. The feature matrix lists them.
Where to go next
| Topic | Page |
|---|---|
| First queries | Getting started |
| Pipelines, identifiers, literals, precedence, comments | Syntax |
| The grammar as implemented | Grammar |
| Types and conversions | Data types |
| Operators, NULL handling, conditions | Expressions |
| Free-text and field search | Search semantics |
| The main commands | Command guide, command support table |
| Scalar functions | Function guide, function table |
| Aggregations | Aggregation guide, aggregation table |
| Time series | Time series |
| Joins, lookups, subsearches | Joins and subsearches |
| What is and is not supported | Feature matrix |
| Error codes and positions | Error handling |
| Worked queries | Examples |
| How a plan runs; making queries fast | Pipeline execution, Performance |
| Compiler internals | Architecture, PPL-to-IR compilation, IR specification, IR optimizer |
| Extending the language | Adding commands, Adding functions |
The command, function and aggregation tables are generated from the
catalogs in pkg/ppl by go run ./internal/docgen. GET /api/v1/catalog
returns the same catalogs as JSON.