111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
---
|
|
layout: default
|
|
title: SQL and PPL CLI
|
|
parent: SQL and PPL
|
|
nav_order: 3
|
|
---
|
|
|
|
# SQL and PPL CLI
|
|
|
|
The SQL and PPL command line interface (CLI) is a standalone Python application that you can launch with the `opensearchsql` command.
|
|
|
|
To use the SQL and PPL CLI, install the SQL plugin on your OpenSearch instance, run the CLI using MacOS or Linux, and connect to any valid OpenSearch endpoint.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
The SQL and PPL CLI has the following features:
|
|
|
|
- Multi-line input
|
|
- PPL support
|
|
- Autocomplete for SQL syntax and index names
|
|
- Syntax highlighting
|
|
- Formatted output:
|
|
- Tabular format
|
|
- Field names with color
|
|
- Enabled horizontal display (by default) and vertical display when output is too wide for your terminal, for better visualization
|
|
- Pagination for large output
|
|
- Works with or without security enabled
|
|
- Supports loading configuration files
|
|
- Supports all SQL plugin queries
|
|
|
|
## Install
|
|
|
|
Launch your local OpenSearch instance and make sure you have the SQL plugin installed.
|
|
|
|
1. Install the CLI:
|
|
```console
|
|
pip3 install opensearchsql
|
|
```
|
|
|
|
The SQL CLI only works with Python 3.
|
|
{: .note }
|
|
|
|
2. To launch the CLI, run:
|
|
```console
|
|
opensearchsql https://localhost:9200 --username admin --password admin
|
|
```
|
|
By default, the `opensearchsql` command connects to http://localhost:9200.
|
|
|
|
## Configure
|
|
|
|
When you first launch the SQL CLI, a configuration file is automatically created at `~/.config/opensearchsql-cli/config` (for MacOS and Linux), the configuration is auto-loaded thereafter.
|
|
|
|
You can configure the following connection properties:
|
|
|
|
- `endpoint`: You do not need to specify an option. Anything that follows the launch command `opensearchsql` is considered as the endpoint. If you do not provide an endpoint, by default, the SQL CLI connects to http://localhost:9200.
|
|
- `-u/-w`: Supports username and password for HTTP basic authentication, such as with the security plugin or fine-grained access control for Amazon OpenSearch Service.
|
|
- `--aws-auth`: Turns on AWS sigV4 authentication to connect to an Amazon OpenSearch endpoint. Use with the AWS CLI (`aws configure`) to retrieve the local AWS configuration to authenticate and connect.
|
|
|
|
For a list of all available configurations, see [clirc](https://github.com/opensearch-project/sql/blob/main/sql-cli/src/opensearch_sql_cli/conf/clirc).
|
|
|
|
## Using the CLI
|
|
|
|
1. Run the CLI tool. If your cluster runs with the default security settings, use the following command:
|
|
```console
|
|
opensearchsql --username admin --password admin https://localhost:9200
|
|
```
|
|
If your cluster runs without security, run:
|
|
```console
|
|
opensearchsql
|
|
```
|
|
|
|
2. Run a sample SQL command:
|
|
```sql
|
|
SELECT * FROM accounts;
|
|
```
|
|
|
|
By default, you see a maximum output of 200 rows. To show more results, add a `LIMIT` clause with the desired value.
|
|
|
|
To exit the CLI tool, select **Ctrl+D**.
|
|
{: .tip }
|
|
|
|
## Using the CLI with PPL
|
|
|
|
1. Run the CLI by specifying the query language:
|
|
```console
|
|
opensearchsql -l ppl <params>
|
|
```
|
|
|
|
2. Execute a PPL query:
|
|
```sql
|
|
source=accounts | fields firstname, lastname
|
|
```
|
|
|
|
## Query options
|
|
|
|
Run a single query with the following command line options:
|
|
|
|
- `-q`: Follow by a single query
|
|
- `-f`: Specify JDBC or raw format output
|
|
- `-v`: Display data vertically
|
|
- `-e`: Translate SQL to DSL
|
|
|
|
## CLI options
|
|
|
|
- `--help`: Help page for options
|
|
- `-l`: Query language option. Available options are `sql` and `ppl`. Default is `sql`
|
|
- `-p`: Always use pager to display output
|
|
- `--clirc`: Provide path for the configuration file
|