OpenSearch PPL Query

Write and run OpenSearch Piped Processing Language queries in .ppl files, and see the results without leaving the editor.

Features

• Syntax highlighting for .ppl files, covering PPL commands, functions, keywords, strings, and comments.
• Completion for commands and functions, and for the field names of the index a query sources — press Ctrl+Space, or type | or a space.
• Snippets for the common shapes: src, stats, where, and others.
• Run the query with Ctrl+Enter, or the run button in the editor title bar.
• Results panel with the rows returned, shown in the PPL panel or beside the editor, with row filtering, sortable columns, and a Copy as CSV button that copies the currently filtered and sorted rows.
• Inline error reporting: a query the cluster rejects is underlined at the offending token.

Requirements

This extension runs queries by invoking the pplquery command-line tool, which is installed separately. It is not bundled.

cpanm OpenSearch::PPLQuery

Full installation instructions are in the pplquery manual.

The extension expects pplquery on your PATH. If it is installed elsewhere, set pplquery.path to the full path of the executable.

Getting started

1. Install the pplquery CLI, as above.
2. Create a file ending in .ppl.
3. Put a connection header at the beginning of the file, select an external connection file from the controls above line 1, or configure the CLI through its PPLQUERY_* environment variables.
4. Write a query and press Ctrl+Enter.

Running a query automatically saves the active .ppl document before sending the query to the CLI.

// pplquery
// url: https://cluster.example.com:9200
// user: analyst
// password-environment: PPLQUERY_ANALYST_PASSWORD

# Failed requests, busiest hosts first.
source = access_logs
| where status >= 500
| stats count() as failures by host
| sort - failures
| head 20

Connections and configuration

Connection metadata belongs in a // pplquery header on line 1 of each query file. Header fields are contiguous // key: value lines followed by a required blank separator line. Supported fields are url, user, password-environment, password-file, ca-file, tls-verify, and timeout. The extension sends the header to the CLI for strict validation and connection handling.

With CodeLens enabled, every .ppl document has a control row above line 1 containing Run Query and Connection: Header/env. Click the connection control to open a compact list of the active file, recently selected files, and *.pplconn files in the workspace. Choose Browse... only when the file is elsewhere. The control displays the selected filename and adds Clear Connection. The absolute path and recent list are retained in VS Code workspace state, not user or workspace settings, and the active file applies to query execution and field completion in that workspace. The same select and clear actions are available from the Command Palette.

By default, Browse... uses the operating system's file dialog. To use VS Code's themed simple file dialog instead, set files.simpleDialog.enable to true in User or Workspace settings. This setting affects all VS Code file dialogs in that scope.

Without an external selection, the extension invokes pplquery --format json -. With one, it invokes pplquery --connection-file FILE --format json -. Under the CLI's connection-file rules, a complete leading header in the query is stripped and ignored; connection-file fields take precedence over environment values, while environment values can fill fields absent from the connection file.

Passwords are never stored in settings, workspace state, or field-cache keys. Without an external connection file, a syntactically valid query header may name a variable in the approved namespace, for example password-environment: PPLQUERY_ANALYST_PASSWORD. When that exact variable is absent, running the query prompts for it, identifies the variable and header endpoint, holds the value in memory by variable name for the extension session, and injects it only when a query requests that variable. Field completion never prompts. The extension does not read a selected connection file, so a password-environment named there must already exist in the extension environment; use password-file when interactive environment setup is undesirable. Malformed headers, password-file references, unrelated environment variables, and ignored query headers do not trigger a prompt. A query that names a password environment variable authorizes disclosure of that secret to its selected endpoint, so treat query files as security-sensitive input.

Commands

Field names are cached per index and connection identity for completion. Selecting or clearing a connection file clears this cache automatically. Run Refresh PPL Field Names after a mapping or the contents of the selected connection file change.

Installing outside the Marketplace

Editors that do not use the Visual Studio Marketplace can install the packaged .vsix from the releases page:

code --install-extension pplquery-1.0.0.vsix

Substitute your editor's own command for code. The same file can be installed from the Extensions view: open the ... menu and choose Install from VSIX.

Links

• Source, issues, and releases: https://codeberg.org/brainbuz/pplquery
• OpenSearch PPL reference: https://opensearch.org/docs/latest/search-plugins/sql/ppl/index/

License

GNU General Public License version 3 or later. Copyright 2026 John Karr.