From 2e619319049032ef26d5c9f5e567e04893d54345 Mon Sep 17 00:00:00 2001 From: Yury Fridlyand Date: Wed, 6 Jul 2022 13:41:31 -0700 Subject: [PATCH 1/3] Merge pull request #1 from Yury-Fridlyand/dev-update-sql-relevance-docs Update SQL plugin relevance functions documentation. Co-authored-by: MaxKsyunz Signed-off-by: Yury Fridlyand --- _ml-commons-plugin/index.md | 2 +- _observability-plugin/app-analytics.md | 4 +- _observability-plugin/event-analytics.md | 4 +- _observability-plugin/index.md | 3 +- _observability-plugin/operational-panels.md | 2 +- _observability-plugin/ppl.md | 10 + _observability-plugin/ppl/datatypes.md | 36 -- _observability-plugin/ppl/endpoint.md | 24 - _observability-plugin/ppl/functions.md | 10 - _observability-plugin/ppl/protocol.md | 71 --- _observability-plugin/ppl/settings.md | 49 -- _opensearch/data-streams.md | 2 +- _search-plugins/sql/cli.md | 61 ++- _search-plugins/sql/datatypes.md | 4 +- _search-plugins/sql/endpoints.md | 66 +-- _search-plugins/sql/full-text.md | 490 ++++++++++++++++++ _search-plugins/sql/functions.md | 6 +- .../sql}/identifiers.md | 6 +- _search-plugins/sql/index.md | 63 +-- _search-plugins/sql/limitation.md | 71 +-- _search-plugins/sql/monitoring.md | 4 +- .../sql/ppl/functions.md | 164 +----- .../sql}/ppl/index.md | 13 +- _search-plugins/sql/ppl/syntax.md | 70 +++ _search-plugins/sql/protocol.md | 75 ++- _search-plugins/sql/settings.md | 44 +- _search-plugins/sql/sql-full-text.md | 205 -------- _search-plugins/sql/{ => sql}/aggregations.md | 1 + _search-plugins/sql/{ => sql}/basic.md | 1 + _search-plugins/sql/{ => sql}/complex.md | 1 + _search-plugins/sql/{ => sql}/delete.md | 1 + _search-plugins/sql/sql/functions.md | 202 ++++++++ _search-plugins/sql/sql/index.md | 68 +++ _search-plugins/sql/{ => sql}/jdbc.md | 5 + _search-plugins/sql/{ => sql}/metadata.md | 1 + _search-plugins/sql/{ => sql}/odbc.md | 61 +-- _search-plugins/sql/{ => sql}/partiql.md | 3 +- _search-plugins/sql/troubleshoot.md | 4 +- _search-plugins/sql/workbench.md | 1 + 39 files changed, 1105 insertions(+), 803 deletions(-) create mode 100644 _observability-plugin/ppl.md delete mode 100644 _observability-plugin/ppl/datatypes.md delete mode 100644 _observability-plugin/ppl/endpoint.md delete mode 100644 _observability-plugin/ppl/functions.md delete mode 100644 _observability-plugin/ppl/protocol.md delete mode 100644 _observability-plugin/ppl/settings.md create mode 100644 _search-plugins/sql/full-text.md rename {_observability-plugin/ppl => _search-plugins/sql}/identifiers.md (95%) rename _observability-plugin/ppl/commands.md => _search-plugins/sql/ppl/functions.md (81%) rename {_observability-plugin => _search-plugins/sql}/ppl/index.md (91%) create mode 100644 _search-plugins/sql/ppl/syntax.md delete mode 100644 _search-plugins/sql/sql-full-text.md rename _search-plugins/sql/{ => sql}/aggregations.md (98%) rename _search-plugins/sql/{ => sql}/basic.md (99%) rename _search-plugins/sql/{ => sql}/complex.md (99%) rename _search-plugins/sql/{ => sql}/delete.md (97%) create mode 100755 _search-plugins/sql/sql/functions.md create mode 100644 _search-plugins/sql/sql/index.md rename _search-plugins/sql/{ => sql}/jdbc.md (63%) rename _search-plugins/sql/{ => sql}/metadata.md (99%) rename _search-plugins/sql/{ => sql}/odbc.md (78%) rename _search-plugins/sql/{ => sql}/partiql.md (99%) diff --git a/_ml-commons-plugin/index.md b/_ml-commons-plugin/index.md index 12142c20657..d18a8b8df39 100644 --- a/_ml-commons-plugin/index.md +++ b/_ml-commons-plugin/index.md @@ -10,7 +10,7 @@ has_toc: false ML Commons for OpenSearch eases the development of machine learning features by providing a set of common machine learning (ML) algorithms through transport and REST API calls. Those calls choose the right nodes and resources for each ML request and monitors ML tasks to ensure uptime. This allows you to leverage existing open-source ML algorithms and reduce the effort required to develop new ML features. -Interaction with the ML Commons plugin occurs through either the [REST API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api) or [AD]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/commands#ad) and [kmeans]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/commands#kmeans) Piped Processing Language (PPL) commands. +Interaction with the ML Commons plugin occurs through either the [REST API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api) or [AD]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/functions#ad) and [kmeans]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/functions#kmeans) Piped Processing Language (PPL) commands. Models [trained]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#train-model) through the ML Commons plugin support model-based algorithms such as kmeans. After you've trained a model enough so that it meets your precision requirements, you can apply the model to [predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#predict) new data safely. diff --git a/_observability-plugin/app-analytics.md b/_observability-plugin/app-analytics.md index 172bb99175f..eecea464810 100644 --- a/_observability-plugin/app-analytics.md +++ b/_observability-plugin/app-analytics.md @@ -18,7 +18,7 @@ To get started, choose **Observability** in OpenSearch Dashboards, and then choo 2. Enter a name for your application and optionally add a description. 3. Do at least one of the following: -- Use [PPL]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index) to specify the base query. +- Use [PPL]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index) to specify the base query. You can't change the base query after the application is created. {: .note } @@ -31,7 +31,7 @@ You can't change the base query after the application is created. ### Create a visualization 1. Choose the **Log Events** tab. -1. Use [PPL]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index) to build upon your base query. +1. Use [PPL]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index) to build upon your base query. 1. Choose the **Visualizations** tab to see your visualizations. 1. Expand the **Save** dropdown menu, enter a name for your visualization, then choose **Save**. diff --git a/_observability-plugin/event-analytics.md b/_observability-plugin/event-analytics.md index 184fb484f57..000d9f49b18 100644 --- a/_observability-plugin/event-analytics.md +++ b/_observability-plugin/event-analytics.md @@ -6,7 +6,7 @@ nav_order: 10 # Event analytics -Event analytics in observability is where you can use [Piped Processing Language]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index) (PPL) queries to build and view different visualizations of your data. +Event analytics in observability is where you can use [Piped Processing Language]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index) (PPL) queries to build and view different visualizations of your data. ## Get started with event analytics @@ -24,7 +24,7 @@ source = opensearch_dashboards_sample_data_logs | fields host | stats count() By default, Dashboards shows results from the last 15 minutes of your data. To see data from a different timeframe, use the date and time selector. -For more information about building PPL queries, see [Piped Processing Language]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index). +For more information about building PPL queries, see [Piped Processing Language]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index). ## Save a visualization diff --git a/_observability-plugin/index.md b/_observability-plugin/index.md index b7d05fe9caa..b2660c55570 100644 --- a/_observability-plugin/index.md +++ b/_observability-plugin/index.md @@ -5,7 +5,6 @@ nav_order: 1 has_children: false redirect_from: - /observability-plugin/ - - /observability-plugin/ --- # About Observability @@ -16,7 +15,7 @@ Observability is collection of plugins and applications that let you visualize d Your experience of exploring data might differ, but if you're new to exploring data to create visualizations, we recommend trying a workflow like the following: -1. Explore data over a certain timeframe using [Piped Processing Language]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index). +1. Explore data over a certain timeframe using [Piped Processing Language]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index). 2. Use [event analytics]({{site.url}}{{site.baseurl}}/observability-plugin/event-analytics) to turn data-driven events into visualizations. ![Sample Event Analytics View]({{site.url}}{{site.baseurl}}/images/event-analytics.png) 3. Create [operational panels]({{site.url}}{{site.baseurl}}/observability-plugin/operational-panels) and add visualizations to compare data the way you like. diff --git a/_observability-plugin/operational-panels.md b/_observability-plugin/operational-panels.md index 9578d7cd6e3..8b8db539a49 100644 --- a/_observability-plugin/operational-panels.md +++ b/_observability-plugin/operational-panels.md @@ -6,7 +6,7 @@ nav_order: 30 # Operational panels -Operational panels in OpenSearch Dashboards are collections of visualizations generated using [Piped Processing Language]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index) (PPL) queries. +Operational panels in OpenSearch Dashboards are collections of visualizations generated using [Piped Processing Language]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index) (PPL) queries. ## Get started with operational panels diff --git a/_observability-plugin/ppl.md b/_observability-plugin/ppl.md new file mode 100644 index 00000000000..f7d53207b9a --- /dev/null +++ b/_observability-plugin/ppl.md @@ -0,0 +1,10 @@ +--- +layout: default +title: Piped Processing Language +nav_order: 40 +--- + +# Piped Processing Language + +Observability plugin uses Piped Processing Language (`PPL`). Since this language is provided by the **SQL Plugin**, the `PPL` documentation can be found in [SQL Plugin]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index/) section. + diff --git a/_observability-plugin/ppl/datatypes.md b/_observability-plugin/ppl/datatypes.md deleted file mode 100644 index 910d96b3120..00000000000 --- a/_observability-plugin/ppl/datatypes.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: default -title: Data Types -parent: Piped processing language -nav_order: 6 ---- - - -# Data types - -The following table shows the data types supported by the PPL plugin and how each one maps to OpenSearch and SQL data types: - -PPL Type | OpenSearch Type | SQL Type -:--- | :--- | :--- -boolean | boolean | BOOLEAN -byte | byte | TINYINT -byte | short | SMALLINT -integer | integer | INTEGER -long | long | BIGINT -float | float | REAL -float | half_float | FLOAT -float | scaled_float | DOUBLE -double | double | DOUBLE -string | keyword | VARCHAR -text | text | VARCHAR -timestamp | date | TIMESTAMP -ip | ip | VARCHAR -timestamp | date | TIMESTAMP -binary | binary | VARBINARY -struct | object | STRUCT -array | nested | STRUCT - -In addition to this list, the PPL plugin also supports the `datetime` type, though it doesn't have a corresponding mapping with OpenSearch. -To use a function without a corresponding mapping, you must explicitly convert the data type to one that does. - -The PPL plugin supports all SQL date and time types. To learn more, see [SQL Data Types]({{site.url}}{{site.baseurl}}/search-plugins/sql/datatypes/). diff --git a/_observability-plugin/ppl/endpoint.md b/_observability-plugin/ppl/endpoint.md deleted file mode 100644 index f4d693faed0..00000000000 --- a/_observability-plugin/ppl/endpoint.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: default -title: Endpoint -parent: Piped processing language -nav_order: 1 ---- - -# Endpoint -Introduced 1.0 -{: .label .label-purple } - -To send a query request to PPL plugin, use the HTTP POST request. -We recommend a POST request because it doesn't have any length limit and it allows you to pass other parameters to the plugin for other functionality. - -Use the `_explain` endpoint for query translation and troubleshooting. - -## Request Format - -To use the PPL plugin with your own applications, send requests to `_plugins/_ppl`, with your query in the request body: - -```json -curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl \ -... -d '{"query" : "source=accounts | fields firstname, lastname"}' -``` diff --git a/_observability-plugin/ppl/functions.md b/_observability-plugin/ppl/functions.md deleted file mode 100644 index 11ea7124858..00000000000 --- a/_observability-plugin/ppl/functions.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: default -title: Functions -parent: Piped processing language -nav_order: 10 ---- - -# Functions - -The PPL plugin supports all SQL functions. To learn more, see [SQL Functions]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/). diff --git a/_observability-plugin/ppl/protocol.md b/_observability-plugin/ppl/protocol.md deleted file mode 100644 index 3636801f133..00000000000 --- a/_observability-plugin/ppl/protocol.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -layout: default -title: Protocol -parent: Piped processing language -nav_order: 2 ---- - -# Protocol - -The PPL plugin provides responses in JDBC format. The JDBC format is widely used because it provides schema information and more functionality such as pagination. Besides JDBC driver, various clients can benefit from the detailed and well formatted response. - -## Response Format - -The body of HTTP POST request can take a few more additional fields with the PPL query: - -```json -curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl \ -... -d '{"query" : "source=accounts | fields firstname, lastname"}' -``` - -The following example shows a normal response where the schema includes a field name and its type and datarows includes the result set: - -```json -{ - "schema": [ - { - "name": "firstname", - "type": "string" - }, - { - "name": "lastname", - "type": "string" - } - ], - "datarows": [ - [ - "Amber", - "Duke" - ], - [ - "Hattie", - "Bond" - ], - [ - "Nanette", - "Bates" - ], - [ - "Dale", - "Adams" - ] - ], - "total": 4, - "size": 4 -} -``` - -If any error occurred, error message and the cause will be returned instead: - -```json -curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl \ -... -d '{"query" : "source=unknown | fields firstname, lastname"}' -{ - "error": { - "reason": "Error occurred in OpenSearch engine: no such index [unknown]", - "details": "org.opensearch.index.IndexNotFoundException: no such index [unknown]\nFor more details, please send request for Json format to see the raw response from opensearch engine.", - "type": "IndexNotFoundException" - }, - "status": 404 -} -``` diff --git a/_observability-plugin/ppl/settings.md b/_observability-plugin/ppl/settings.md deleted file mode 100644 index 8dd7476b649..00000000000 --- a/_observability-plugin/ppl/settings.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: default -title: Settings -parent: Piped processing language -nav_order: 3 ---- - -# Settings - -The PPL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster. - -You can update these settings like any other cluster setting: - -```json -PUT _cluster/settings -{ - "transient": { - "plugins": { - "ppl": { - "enabled": "false" - } - } - } -} -``` - -Similarly, you can also update the settings by sending request to the plugin setting endpoint `_plugins/_query/settings` : -```json -PUT _plugins/_query/settings -{ - "transient": { - "plugins": { - "ppl": { - "enabled": "false" - } - } - } -} -``` - -Requests to `_plugins/_ppl` include index names in the request body, so they have the same access policy considerations as the `bulk`, `mget`, and `msearch` operations. If you set the `rest.action.multi.allow_explicit_index` parameter to `false`, the PPL plugin is disabled. - -You can specify the settings shown in the following table: - -Setting | Description | Default -:--- | :--- | :--- -`plugins.ppl.enabled` | Change to `false` to disable the PPL component. | True -`plugins.query.memory_limit` | Set heap memory usage limit. If a query crosses this limit, it's terminated. | 85% -`plugins.query.size_limit` | Set the maximum number of results that you want to see. This impacts the accuracy of aggregation operations. For example, if you have 1000 documents in an index, by default, only 200 documents are extracted from the index for aggregation. | 200 diff --git a/_opensearch/data-streams.md b/_opensearch/data-streams.md index 69ee1b13215..592957463fc 100644 --- a/_opensearch/data-streams.md +++ b/_opensearch/data-streams.md @@ -262,4 +262,4 @@ You can use wildcards to delete more than one data stream. We recommend deleting data from a data stream using an ISM policy. -You can also use [asynchronous search]({{site.url}}{{site.baseurl}}/search-plugins/async/index/) and [SQL]({{site.url}}{{site.baseurl}}/search-plugins/sql/index/) and [PPL]({{site.url}}{{site.baseurl}}/observability-plugin/ppl/index/) to query your data stream directly. You can also use the security plugin to define granular permissions on the data stream name. +You can also use [asynchronous search]({{site.url}}{{site.baseurl}}/search-plugins/async/index/) and [SQL]({{site.url}}{{site.baseurl}}/search-plugins/sql/index/) and [PPL]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/index/) to query your data stream directly. You can also use the security plugin to define granular permissions on the data stream name. diff --git a/_search-plugins/sql/cli.md b/_search-plugins/sql/cli.md index c2b16f7c5e3..00d4e48fc59 100644 --- a/_search-plugins/sql/cli.md +++ b/_search-plugins/sql/cli.md @@ -1,13 +1,13 @@ --- layout: default -title: SQL CLI -parent: SQL -nav_order: 2 +title: SQL & PPL CLI +parent: SQL Plugin - SQL & PPL +nav_order: 3 --- -# SQL CLI +# SQL & PPL CLI -SQL CLI is a stand-alone Python application that you can launch with the `opensearchsql` command. +CLI is a stand-alone Python application that you can launch with the `opensearchsql` command. Install the SQL plugin to your OpenSearch instance, run the CLI using MacOS or Linux, and connect to any valid OpenSearch end-point. @@ -15,9 +15,10 @@ Install the SQL plugin to your OpenSearch instance, run the CLI using MacOS or L ## Features -SQL CLI has the following features: +CLI has the following features: - Multi-line input +- PPL support - Autocomplete for SQL syntax and index names - Syntax highlighting - Formatted output: @@ -33,26 +34,16 @@ SQL CLI has the following features: Launch your local OpenSearch instance and make sure you have the SQL plugin installed. -To install the SQL CLI: - -1. We suggest you install and activate a python3 virtual environment to avoid changing your local environment: -``` -pip install virtualenv -virtualenv venv -cd venv -source ./bin/activate -``` - -2. Install the CLI: -``` +1. Install the CLI: +```console pip3 install opensearchsql ``` The SQL CLI only works with Python 3. {: .note } -3. To launch the CLI, run: -``` +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. @@ -71,25 +62,38 @@ For a list of all available configurations, see [clirc](https://github.com/opens ## Using the CLI -1. Save the sample [accounts test data](https://github.com/opensearch-project/sql/blob/main/doctest/test_data/accounts.json) file. - -1. Index the sample data. +1. Run the CLI tool. If you cluster runs with default security settings, use following command line: +```console +opensearchsql --username admin --password admin https://localhost:9200 ``` -curl -H "Content-Type: application/x-ndjson" -POST https://localhost:9200/data/_bulk -u 'admin:admin' --insecure --data-binary "@accounts.json" +If your cluster runs without security, run: +```console +opensearchsql ``` -1. Run a sample SQL command: -``` +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. +## Using the CLI with PPL + +1. Run CLI by specifying query language: +```console +opensearchsql -l ppl +``` + +2. Execute a PPL query: +```sql +source=accounts | fields firstname, lastname +``` + ## Query options -Run a single query with the following options: +Run a single query with the following command line options: -- `--help`: Help page for options - `-q`: Follow by a single query - `-f`: Specify JDBC or raw format output - `-v`: Display data vertically @@ -97,6 +101,7 @@ Run a single query with the following options: ## 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 diff --git a/_search-plugins/sql/datatypes.md b/_search-plugins/sql/datatypes.md index a11fa233dd0..1edff1d4c7c 100644 --- a/_search-plugins/sql/datatypes.md +++ b/_search-plugins/sql/datatypes.md @@ -1,8 +1,8 @@ --- layout: default title: Data Types -parent: SQL -nav_order: 73 +parent: SQL Plugin - SQL & PPL +nav_order: 7 --- # Data types diff --git a/_search-plugins/sql/endpoints.md b/_search-plugins/sql/endpoints.md index 95affd3c00b..6a912a403d8 100644 --- a/_search-plugins/sql/endpoints.md +++ b/_search-plugins/sql/endpoints.md @@ -1,8 +1,8 @@ --- layout: default title: Endpoint -parent: SQL -nav_order: 13 +parent: SQL Plugin - SQL & PPL +nav_order: 1 --- @@ -17,20 +17,6 @@ other parameters passed to plugin for other functionality such as prepared statement. And also the explain endpoint is used very often for query translation and troubleshooting. -## GET - -### Description - -You can send HTTP GET request with your query embedded in URL parameter. - -### Example - -SQL query: - -```console ->> curl -H 'Content-Type: application/json' -X GET localhost:9200/_plugins/_sql?sql=SELECT * FROM accounts -``` - ## POST ### Description @@ -51,10 +37,8 @@ SQL query: ### Description -To translate your query, send it to explain endpoint. The explain output -is OpenSearch domain specific language (DSL) in JSON format. You can -just copy and paste it to your console to run it against OpenSearch -directly. +The SQL & PPL plugin has an `explain` feature that shows how a query would be executed against OpenSearch, which is useful for debugging and development. A `POST` request to `_plugins/_sql/_explain` or `_plugins/_ppl/_explain` endpoints will return OpenSearch domain specific language (DSL) in JSON format explaining the query. +The plugin would translate the query into OpenSearch Domain Specific Language (`DSL`) in `JSON` format. It could be executed on REST API using `curl` or in Dashboards Console. ### Example @@ -66,45 +50,15 @@ Explain query: }' ``` -Explain: +An explain query could be used for `PPL` as well: -```json -{ - "from": 0, - "size": 200, - "query": { - "bool": { - "filter": [{ - "bool": { - "must": [{ - "range": { - "age": { - "from": 20, - "to": null, - "include_lower": false, - "include_upper": true, - "boost": 1.0 - } - } - }], - "adjust_pure_negative": true, - "boost": 1.0 - } - }], - "adjust_pure_negative": true, - "boost": 1.0 - } - }, - "_source": { - "includes": [ - "firstname", - "lastname" - ], - "excludes": [] - } -} +```console +>> curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl/_explain -d '{ + "query" : "source=accounts | fields firstname, lastname" +}' ``` +For queries that require post-processing, the `explain` response includes a query plan in addition to the OpenSearch DSL. For those queries that don't require post processing, you can see a complete DSL. ## Cursor diff --git a/_search-plugins/sql/full-text.md b/_search-plugins/sql/full-text.md new file mode 100644 index 00000000000..c772f01ba46 --- /dev/null +++ b/_search-plugins/sql/full-text.md @@ -0,0 +1,490 @@ +--- +layout: default +title: Full-Text Search +parent: SQL Plugin - SQL & PPL +nav_order: 11 +--- + +# Full-text search + +Use SQL commands for full-text search. The SQL plugin supports a subset of full-text queries available in OpenSearch. + +To learn about full-text queries in OpenSearch, see [Full-text queries]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/). + +## Match + +Use the `MATCH` function to search documents that match a `string`, `number`, `date`, or `boolean` value for a given field. + +### Syntax + +```sql +match(field_expression, query_expression[, option=]*) +``` + +You can specify the following options in any order: + +- `analyzer` +- `auto_generate_synonyms_phrase` +- `fuzziness` +- `max_expansions` +- `prefix_length` +- `fuzzy_transpositions` +- `fuzzy_rewrite` +- `lenient` +- `operator` +- `minimum_should_match` +- `zero_terms_query` +- `boost` + +Please, refer to `match` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#match) for parameter description and supported values. + +### Example 1: Search the `message` field for the text "this is a test": + +```json +GET my_index/_search +{ + "query": { + "match": { + "message": "this is a test" + } + } +} +``` + +*SQL query:* +```sql +SELECT message FROM my_index WHERE match(message, "this is a test") +``` +*PPL query:* +```ppl +SOURCE=my_index | WHERE match(message, "this is a test") | FIELDS message +``` + +### Example 2: Search the `message` field with the `operator` parameter: + +```json +GET my_index/_search +{ + "query": { + "match": { + "message": { + "query": "this is a test", + "operator": "and" + } + } + } +} +``` + +*SQL query:* +```sql +SELECT message FROM my_index WHERE match(message, "this is a test", operator='and') +``` +*PPL query:* +```ppl +SOURCE=my_index | WHERE match(message, "this is a test", operator='and') | FIELDS message +``` + +### Example 3: Search the `message` field with the `operator` and `zero_terms_query` parameters: + +```json +GET my_index/_search +{ + "query": { + "match": { + "message": { + "query": "to be or not to be", + "operator": "and", + "zero_terms_query": "all" + } + } + } +} +``` + +*SQL query:* +```sql +SELECT message FROM my_index WHERE match(message, "this is a test", operator='and', zero_terms_query='all') +``` +*PPL query:* +```sql +SOURCE=my_index | WHERE match(message, "this is a test", operator='and', zero_terms_query='all') | FIELDS message +``` + +## Multi match + +To search for text in multiple fields, use `MULTI_MATCH` function. This function maps to the `multi_match` query used in search engine, to returns the documents that match a provided text, number, date or boolean value with a given field or fields. + +### Syntax + +The `MULTI_MATCH` function lets you *boost* certain fields using **^** character. Boosts are multipliers that weigh matches in one field more heavily than matches in other fields. The syntax allows to specify the fields in double quotes, single quotes, surrounded by backticks, or unquoted. Use star ``"*"`` to search all fields. Star symbol should be quoted. + +```sql +multi_match([field_expression+], query_expression[, option=]*) +``` + +The weight is optional and is specified after the field name. It could be delimited by the `caret` character -- `^` or by whitespace. Please, refer to examples below: + +```sql +multi_match(["Tags" ^ 2, 'Title' 3.4, `Body`, Comments ^ 0.3], ...) +multi_match(["*"], ...) +``` + +You can specify the following options for `MULTI_MATCH` in any order: + +- `analyzer` +- `auto_generate_synonyms_phrase` +- `cutoff_frequency` +- `fuzziness` +- `fuzzy_transpositions` +- `lenient` +- `max_expansions` +- `minimum_should_match` +- `operator` +- `prefix_length` +- `tie_breaker` +- `type` +- `slop` +- `zero_terms_query` +- `boost` + +Please, refer to `multi_match` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#multi-match) for parameter description and supported values. + +### For example, REST API search for `Dale` in either the `firstname` or `lastname` fields: + +```json +GET accounts/_search +{ + "query": { + "multi_match": { + "query": "Lane Street", + "fields": [ "address" ], + } + } +} +``` +could be called from *SQL* using `multi_match` function +```sql +SELECT firstname, lastname +FROM accounts +WHERE multi_match(['*name'], 'Dale') +``` +or `multi_match` *PPL* function +```sql +SOURCE=accounts | WHERE multi_match(['*name'], 'Dale') | fields firstname, lastname +``` + +| firstname | lastname +:--- | :--- +Dale | Adams + +## Query string + +To split text based on operators, use the `QUERY_STRING` function. The `QUERY_STRING` function supports logical connectives, wildcard, regex, and proximity search. +This function maps to the to the `query_string` query used in search engine, to return the documents that match a provided text, number, date or boolean value with a given field or fields. + +### Syntax + +The `QUERY_STRING` function has syntax similar to `MATCH_QUERY` and lets you *boost* certain fields using **^** character. Boosts are multipliers that weigh matches in one field more heavily than matches in other fields. The syntax allows to specify the fields in double quotes, single quotes, surrounded by backticks, or unquoted. Use star ``"*"`` to search all fields. Star symbol should be quoted. + +```sql +query_string([field_expression+], query_expression[, option=]*) +``` + +The weight is optional and is specified after the field name. It could be delimited by the `caret` character -- `^` or by whitespace. Please, refer to examples below: + +```sql +query_string(["Tags" ^ 2, 'Title' 3.4, `Body`, Comments ^ 0.3], ...) +query_string(["*"], ...) +``` + +You can specify the following options for `QUERY_STRING` in any order: + +- `analyzer` +- `allow_leading_wildcard` +- `analyze_wildcard` +- `auto_generate_synonyms_phrase_query` +- `boost` +- `default_operator` +- `enable_position_increments` +- `fuzziness` +- `fuzzy_rewrite` +- `escape` +- `fuzzy_max_expansions` +- `fuzzy_prefix_length` +- `fuzzy_transpositions` +- `lenient` +- `max_determinized_states` +- `minimum_should_match` +- `quote_analyzer` +- `phrase_slop` +- `quote_field_suffix` +- `rewrite` +- `type` +- `tie_breaker` +- `time_zone` + +Please, refer to `query_string` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#query-string) for parameter description and supported values. + +### Example of using `query_string` in SQL and PPL queries: + +The REST API search request + +```json +GET accounts/_search +{ + "query": { + "query_string": { + "query": "Lane Street", + "fields": [ "address" ], + } + } +} +``` + +could be called from *SQL* + +```sql +SELECT account_number, address +FROM accounts +WHERE query_string(['address'], 'Lane Street', default_operator='OR') +``` + +or from *PPL* + +```sql +SOURCE=accounts | WHERE query_string(['address'], 'Lane Street', default_operator='OR') | fields account_number, address +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane +6 | 671 Bristol Street +13 | 789 Madison Street + +## Match phrase + +To search for exact phrases, use `MATCHPHRASE` or `MATCH_PHRASE` functions. + +### Syntax + +```sql +matchphrasequery(field_expression, query_expression) +matchphrase(field_expression, query_expression[, option=]*) +match_phrase(field_expression, query_expression[, option=]*) +``` + +The `MATCHPHRASE`/`MATCH_PHRASE` functions let you specify the following options in any order: + +- `analyzer` +- `slop` +- `zero_terms_query` +- `boost` + +Please, refer to `match_phrase` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#match-phrase) for parameter description and supported values. + +### Example of using `match_phrase` in SQL and PPL queries: + +The REST API search request +```json +GET accounts/_search +{ + "query": { + "match_phrase": { + "address": { + "query": "880 Holmes Lane" + } + } + } +} +``` +could be called from *SQL* +```sql +SELECT account_number, address +FROM accounts +WHERE match_phrase(address, '880 Holmes Lane') +``` +or *PPL* +```sql +SOURCE=accounts | WHERE match_phrase(address, '880 Holmes Lane') | FIELDS account_number, address +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane + + +## Simple query string + +The `simple_query_string` function maps to the `simple_query_string` query in OpenSearch. It returns the documents that match a provided text, number, date or boolean value with a given field or fields. +The **^** lets you *boost* certain fields. Boosts are multipliers that weigh matches in one field more heavily than matches in other fields. + +### Syntax + +The syntax allows to specify the fields in double quotes, single quotes, surrounded by backticks, or unquoted. Use star ``"*"`` to search all fields. Star symbol should be quoted. + +```sql +simple_query_string([field_expression+], query_expression[, option=]*) +``` + +The weight is optional and is specified after the field name. It could be delimited by the `caret` character -- `^` or by whitespace. Please, refer to examples below: + +```sql +simple_query_string(["Tags" ^ 2, 'Title' 3.4, `Body`, Comments ^ 0.3], ...) +simple_query_string(["*"], ...) +``` + +You can specify the following options for `SIMPLE_QUERY_STRING` in any order: + +- `analyze_wildcard` +- `analyzer` +- `auto_generate_synonyms_phrase_query` +- `boost` +- `default_operator` +- `flags` +- `fuzzy_max_expansions` +- `fuzzy_prefix_length` +- `fuzzy_transpositions` +- `lenient` +- `minimum_should_match` +- `quote_field_suffix` + +Please, refer to `simple_query_string` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#simple-query-string) to check parameter meanings and available values. + +### *Example* of using `simple_query_string` in SQL and PPL queries: + +The REST API search request +```json +GET accounts/_search +{ + "query": { + "simple_query_string": { + "query": "Lane Street", + "fields": [ "address" ], + } + } +} +``` +could be called from *SQL* +```sql +SELECT account_number, address +FROM accounts +WHERE simple_query_string(['address'], 'Lane Street', default_operator='OR') +``` +or from *PPL* +```sql +SOURCE=accounts | WHERE simple_query_string(['address'], 'Lane Street', default_operator='OR') | fields account_number, address +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane +6 | 671 Bristol Street +13 | 789 Madison Street + +## Match phrase prefix + +To search for phrases by given prefix, use `MATCH_PHRASE_PREFIX` function to make a prefix query out of the last term in the query string. + +### Syntax + +```sql +match_phrase_prefix(field_expression, query_expression[, option=]*) +``` + +The `MATCH_PHRASE_PREFIX` function lets you specify the following options in any order: + +- `analyzer` +- `slop` +- `max_expansions` +- `zero_terms_query` +- `boost` + +Please, refer to `match_phrase_prefix` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#match-phrase-prefix) for parameter description and supported values. + +### *Example* of using `match_phrase_prefix` in SQL and PPL queries: + +The REST API search request +```json +GET accounts/_search +{ + "query": { + "match_phrase_prefix": { + "author": { + "query": "Alexander Mil" + } + } + } +} +``` +could be called from *SQL* +```sql +SELECT author, title +FROM books +WHERE match_phrase_prefix(author, 'Alexander Mil') +``` +or *PPL* +```sql +source=books | where match_phrase_prefix(author, 'Alexander Mil') | fields author, title +``` + +| author | title +:--- | :--- +Alan Alexander Milne | The House at Pooh Corner +Alan Alexander Milne | Winnie-the-Pooh + + +## Match boolean prefix + +Use the `match_bool_prefix` function to search documents that match text only for a given field prefix. + +### Syntax + +```sql +match_bool_prefix(field_expression, query_expression[, option=]*) +``` + +The `MATCH_BOOL_PREFIX` function lets you specify the following options in any order: + +- `minimum_should_match` +- `fuzziness` +- `prefix_length` +- `max_expansions` +- `fuzzy_transpositions` +- `fuzzy_rewrite` +- `boost` +- `analyzer` +- `operator` + +Please, refer to `match_bool_prefix` query [documentation]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/#match-boolean-prefix) for parameter description and supported values. + +### Example of using `match_bool_prefix` in SQL and PPL queries: + +The REST API search request +```json +GET accounts/_search +{ + "query": { + "match_bool_prefix": { + "address": { + "query": "Bristol Stre" + } + } + } +} +``` +could be called from *SQL* +```sql +SELECT firstname, address +FROM accounts +WHERE match_bool_prefix(address, 'Bristol Stre') +``` +or *PPL* +```sql +source=accounts | where match_bool_prefix(address, 'Bristol Stre') | fields firstname, address +``` + +| firstname | address +:--- | :--- +Hattie | 671 Bristol Street +Nanette | 789 Madison Street diff --git a/_search-plugins/sql/functions.md b/_search-plugins/sql/functions.md index 215300fba34..c96fd0776e2 100644 --- a/_search-plugins/sql/functions.md +++ b/_search-plugins/sql/functions.md @@ -1,7 +1,7 @@ --- layout: default title: Functions -parent: SQL +parent: SQL Plugin - SQL & PPL nav_order: 10 --- @@ -131,3 +131,7 @@ Function | Specification | Example if | `if(boolean, es_type, es_type) -> es_type` | `SELECT if(false, 0, 1) FROM my-index LIMIT 1`, `SELECT if(true, 0, 1) FROM my-index LIMIT 1` ifnull | `ifnull(es_type, es_type) -> es_type` | `SELECT ifnull('hello', 1) FROM my-index LIMIT 1`, `SELECT ifnull(null, 1) FROM my-index LIMIT 1` isnull | `isnull(es_type) -> integer` | `SELECT isnull(null) FROM my-index LIMIT 1`, `SELECT isnull(1) FROM my-index LIMIT 1` + +## Relevance Based Search (Full-Text Search) + +These functions are only available in the `WHERE` clause. Their description and usage examples in SQL and PPL can be found on [full-text queries page]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/). diff --git a/_observability-plugin/ppl/identifiers.md b/_search-plugins/sql/identifiers.md similarity index 95% rename from _observability-plugin/ppl/identifiers.md rename to _search-plugins/sql/identifiers.md index aac5b744dea..447e7645f56 100644 --- a/_observability-plugin/ppl/identifiers.md +++ b/_search-plugins/sql/identifiers.md @@ -1,8 +1,8 @@ --- layout: default title: Identifiers -parent: Piped processing language -nav_order: 7 +parent: SQL Plugin - SQL & PPL +nav_order: 6 --- @@ -28,7 +28,7 @@ For regular identifiers, you can use the name without any back tick or escape ch In this example, `source`, `fields`, `account_number`, `firstname`, and `lastname` are all identifiers. Out of these, the `source` field is a reserved identifier. ```sql -source=accounts | fields account_number, firstname, lastname; +SELECT account_number, firstname, lastname FROM accounts; ``` | account_number | firstname | lastname | diff --git a/_search-plugins/sql/index.md b/_search-plugins/sql/index.md index a3c1ee95bd9..4a0e4e4d8da 100644 --- a/_search-plugins/sql/index.md +++ b/_search-plugins/sql/index.md @@ -1,6 +1,6 @@ --- layout: default -title: SQL +title: SQL Plugin - SQL & PPL nav_order: 38 has_children: true has_toc: false @@ -8,69 +8,10 @@ redirect_from: - /search-plugins/sql/ --- -# SQL +# SQL Plugin - SQL & PPL OpenSearch SQL lets you write queries in SQL rather than the [OpenSearch query domain-specific language (DSL)]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text). If you're already familiar with SQL and don't want to learn the query DSL, this feature is a great option. - -## Workbench - -The easiest way to get familiar with the SQL plugin is to use **Query Workbench** in OpenSearch Dashboards to test various queries. To learn more, see [Workbench]({{site.url}}{{site.baseurl}}/search-plugins/sql/workbench/). - -![OpenSearch Dashboards SQL UI plugin]({{site.url}}{{site.baseurl}}/images/sql.png) - - -## REST API - -To use the SQL plugin with your own applications, send requests to `_plugins/_sql`: - -```json -POST _plugins/_sql -{ - "query": "SELECT * FROM my-index LIMIT 50" -} -``` - -Here’s how core SQL concepts map to OpenSearch: - -SQL | OpenSearch -:--- | :--- -Table | Index -Row | Document -Column | Field - -You can query multiple indices by listing them or using wildcards: - -```json -POST _plugins/_sql -{ - "query": "SELECT * FROM my-index1,myindex2,myindex3 LIMIT 50" -} - -POST _plugins/_sql -{ - "query": "SELECT * FROM my-index* LIMIT 50" -} -``` - -For a sample [curl](https://curl.haxx.se/) command, try: - -```bash -curl -XPOST https://localhost:9200/_plugins/_sql -u 'admin:admin' -k -H 'Content-Type: application/json' -d '{"query": "SELECT * FROM opensearch_dashboards_sample_data_flights LIMIT 10"}' -``` - -By default, queries return data in JDBC format, but you can also return data in standard OpenSearch JSON, CSV, or raw formats: - -```json -POST _plugins/_sql?format=json|csv|raw -{ - "query": "SELECT * FROM my-index LIMIT 50" -} -``` - -See the rest of this guide for detailed information on request parameters, settings, supported operations, tools, and more. - - ## Contributing To get involved and help us improve the SQL plugin, see the [development guide](https://github.com/opensearch-project/sql/blob/main/DEVELOPER_GUIDE.rst) for instructions on setting up your development environment and building the project. diff --git a/_search-plugins/sql/limitation.md b/_search-plugins/sql/limitation.md index 8a3e8a825b4..6e825f1361e 100644 --- a/_search-plugins/sql/limitation.md +++ b/_search-plugins/sql/limitation.md @@ -1,62 +1,18 @@ --- layout: default title: Limitations -parent: SQL -nav_order: 18 +parent: SQL Plugin - SQL & PPL +nav_order: 99 --- # Limitations The SQL plugin has the following limitations: -## SELECT FROM WHERE - -### Select literal is not supported - -The select literal expression is not supported. For example, `Select 1` is not supported. - - -### Where clause does not support arithmetic operations - -The `WHERE` clause does not support expressions. For example, `SELECT FlightNum FROM opensearch_dashboards_sample_data_flights where (AvgTicketPrice + 100) <= 1000` is not supported. - - -### Aggregation over expression is not supported +## Aggregation over expression is not supported You can only apply aggregation on fields, aggregations can't accept an expression as a parameter. For example, `avg(log(age))` is not supported. - -### Conflict type in multiple index query - -Queries using wildcard index fail if the index has the field with a conflict type. -For example, if you have two indices with field `a`: - -``` -POST conflict_index_1/_doc/ -{ - "a": { - "b": 1 - } -} - -POST conflict_index_2/_doc/ -{ - "a": { - "b": 1, - "c": 2 - } -} -``` - -Then, the query fails because of the field mapping conflict. The query `SELECT * FROM conflict_index*` also fails for the same reason. - -```sql -Error occurred in OpenSearch engine: Different mappings are not allowed for the same field[a]: found [{properties:{b:{type:long},c:{type:long}}}] and [{properties:{b:{type:long}}}] ", - "details": "com.amazon.opensearch.sql.rewriter.matchtoterm.VerificationException: Different mappings are not allowed for the same field[a]: found [{properties:{b:{type:long},c:{type:long}}}] and [{properties:{b:{type:long}}}] \nFor more details, please send request for Json format to see the raw response from opensearch engine.", - "type": "VerificationException -``` - - ## Subquery in the FROM clause Subquery in the `FROM` clause in this format: `SELECT outer FROM (SELECT inner)` is supported only when the query is merged into one query. For example, the following query is supported: @@ -76,7 +32,6 @@ But, if the outer query has `GROUP BY` or `ORDER BY`, then it's not supported. The `join` query does not support aggregations on the joined result. For example, e.g. `SELECT depo.name, avg(empo.age) FROM empo JOIN depo WHERE empo.id == depo.id GROUP BY depo.name` is not supported. - ## Pagination only supports basic queries The pagination query enables you to get back paginated responses. @@ -116,3 +71,23 @@ The response in JDBC format with cursor id. ``` The query with `aggregation` and `join` does not support pagination for now. + +## Query processing engines + +The plugin has two query processing engines. Most of the features are supported by both engines, but only the new engine is actively being developed. A query is first executed on the new engine (`V2`) and then falls back to the old one (`V1`) in case of failure. That means a query with new functions A (included in `V2` only) and B (`V1` only and not yet included in `V2`) will fail with an error response. + +### V1 engine limitations + +* The select literal expression without `FROM` clause is not supported. For example, `SELECT 1` is not supported. +* The `WHERE` clause does not support expressions. For example, `SELECT FlightNum FROM opensearch_dashboards_sample_data_flights where (AvgTicketPrice + 100) <= 1000` is not supported. +* Most of [relevancy search functions]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/) are implemented in the `V2` engine only. + +Such queries are successfully executed by `V2` engine unless they have `V1`-specific functions. Likely you will never meet these limitations. + +### V2 engine limitations + +* [Cursor feature](#pagination-only-supports-basic-queries) supported by the `V1` engine only. +Please, track [GitHub issue #656](https://github.com/opensearch-project/sql/issues/656) for support `cursor`/`pagination` in `V2` engine. +* `V2` engine doesn't track query execution time, so slow queries are not reported. +* `V2` query engine not only runs queries in OpenSearch engine but also supports post-processing for complicated queries. Accordingly, explain output is no longer pure OpenSearch `DSL`, but also includes query plan information from the `V2` query engine. +* `V2` engine doesn't support [`SCORE_QUERY`]({{site.url}}{{site.baseurl}}/search-plugins/sql/sql/functions#score-query) and [`WILDCARD_QUERY`]({{site.url}}{{site.baseurl}}/search-plugins/sql/sql/functions#wildcard-query) functions. diff --git a/_search-plugins/sql/monitoring.md b/_search-plugins/sql/monitoring.md index b8f6478acc1..78de378b902 100644 --- a/_search-plugins/sql/monitoring.md +++ b/_search-plugins/sql/monitoring.md @@ -1,8 +1,8 @@ --- layout: default title: Monitoring -parent: SQL -nav_order: 15 +parent: SQL Plugin - SQL & PPL +nav_order: 95 --- # Monitoring diff --git a/_observability-plugin/ppl/commands.md b/_search-plugins/sql/ppl/functions.md similarity index 81% rename from _observability-plugin/ppl/commands.md rename to _search-plugins/sql/ppl/functions.md index 98e05887edf..1ed462440df 100644 --- a/_observability-plugin/ppl/commands.md +++ b/_search-plugins/sql/ppl/functions.md @@ -1,69 +1,14 @@ --- layout: default -title: Commands -parent: Piped processing language -nav_order: 4 +title: Functions +parent: PPL - Piped Processing Language +grand_parent: SQL Plugin - SQL & PPL +nav_order: 2 --- +# Functions -# Commands - -Start a PPL query with a `search` command to reference a table to search from. You can have the commands that follow in any order. - -In the following example, the `search` command refers to an `accounts` index as the source, then uses `fields` and `where` commands for the conditions: - -```sql -search source=accounts -| where age > 18 -| fields firstname, lastname -``` - -In the below examples, we represent required arguments in angle brackets `< >` and optional arguments in square brackets `[ ]`. -{: .note } - -## search - -Use the `search` command to retrieve a document from an index. You can only use the `search` command as the first command in the PPL query. - -### Syntax - -```sql -search source= [boolean-expression] -``` - -Field | Description | Required -:--- | :--- |:--- -`search` | Specify search keywords. | Yes -`index` | Specify which index to query from. | No -`bool-expression` | Specify an expression that evaluates to a boolean value. | No - -*Example 1*: Get all documents - -To get all documents from the `accounts` index: - -```sql -search source=accounts; -``` - -| account_number | firstname | address | balance | gender | city | employer | state | age | email | lastname | -:--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- -| 1 | Amber | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com | Duke -| 6 | Hattie | 671 Bristol Street | 5686 | M | Dante | Netagy | TN | 36 | hattiebond@netagy.com | Bond -| 13 | Nanette | 789 Madison Street | 32838 | F | Nogal | Quility | VA | 28 | null | Bates -| 18 | Dale | 467 Hutchinson Court | 4180 | M | Orick | null | MD | 33 | daleadams@boink.com | Adams - -*Example 2*: Get documents that match a condition - -To get all documents from the `accounts` index that have either `account_number` equal to 1 or have `gender` as `F`: - -```sql -search source=accounts account_number=1 or gender=\"F\"; -``` - -| account_number | firstname | address | balance | gender | city | employer | state | age | email | lastname | -:--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- -| 1 | Amber | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com | Duke | -| 13 | Nanette | 789 Madison Street | 32838 | F | Nogal | Quility | VA | 28 | null | Bates | +`PPL` supports all [`SQL`]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/) functions, including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few more functions which are available in `PPL` only. ## dedup @@ -743,100 +688,11 @@ search source=accounts | top 1 age by gender; The `top` command is not rewritten to OpenSearch DSL, it is only executed on the coordination node. -## match - -Use the `match` command to search documents that match a `string`, `number`, `date`, or `boolean` value for a given field. - -### Syntax - -```sql -match(field_expression, query_expression[, option=]*) -``` - -You can specify the following options: - -- `analyzer` -- `auto_generate_synonyms_phrase` -- `fuzziness` -- `max_expansions` -- `prefix_length` -- `fuzzy_transpositions` -- `fuzzy_rewrite` -- `lenient` -- `operator` -- `minimum_should_match` -- `zero_terms_query` -- `boost` - -*Example 1*: Search the `message` field: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": "this is a test" - } - } -} -``` - -PPL query: - -```sql -search source=my_index | match field=message query="this is a test" -``` - -*Example 2*: Search the `message` field with the `operator` parameter: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": { - "query": "this is a test", - "operator": "and" - } - } - } -} -``` - -PPL query: - -```sql -search source=my_index | match field=message query="this is a test" operator=and -``` - -*Example 3*: Search the `message` field with the `operator` and `zero_terms_query` parameters: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": { - "query": "to be or not to be", - "operator": "and", - "zero_terms_query": "all" - } - } - } -} -``` - -PPL query: - -```ppl -search source=my_index | where match(message, "this is a test", operator=and, zero_terms_query=all) -``` - ## ad -The `ad` command applies the Random Cut Forest (RCF) algorithm in the ML Commons plugin on the search result returned by a PPL command. Based on the input, the plugin uses two types of RCF algorithms: fixed in time RCF for processing time-series data and batch RCF for processing non-time-series data. +The `ad` command applies the Random Cut Forest (RCF) algorithm in the [ML Commons plugin]({{site.url}}{{site.baseurl}}/ml-commons-plugin/index/) on the search result returned by a PPL command. Based on the input, the plugin uses two types of RCF algorithms: fixed in time RCF for processing time-series data and batch RCF for processing non-time-series data. -### Fixed In Time RCF For Time-series Data Command Syntax +### Syntax: Fixed In Time RCF For Time-series Data Command ```sql ad @@ -848,7 +704,7 @@ Field | Description | Required `time_decay` | Specifies how much of the recent past to consider when computing an anomaly score. The default value is 0.001. | No `time_field` | Specifies the time filed for RCF to use as time-series data. Must be either a long value, such as the timestamp in miliseconds, or a string value in "yyyy-MM-dd HH:mm:ss".| Yes -### Batch RCF for Non-time-series Data Command Syntax +### Syntax: Batch RCF for Non-time-series Data Command ```sql ad @@ -889,7 +745,7 @@ value | score | anomalous The kmeans command applies the ML Commons plugin's kmeans algorithm to the provided PPL command's search results. -## Syntax +### Syntax ```sql kmeans diff --git a/_observability-plugin/ppl/index.md b/_search-plugins/sql/ppl/index.md similarity index 91% rename from _observability-plugin/ppl/index.md rename to _search-plugins/sql/ppl/index.md index e3c9724a2c9..6c2d49a6713 100644 --- a/_observability-plugin/ppl/index.md +++ b/_search-plugins/sql/ppl/index.md @@ -1,14 +1,17 @@ --- layout: default -title: Piped processing language -nav_order: 40 +title: PPL - Piped Processing Language +parent: SQL Plugin - SQL & PPL +nav_order: 5 has_children: true has_toc: false redirect_from: - - /search-plugins/ppl/ + - /search-plugins/sql/ppl + - /search-plugins/ppl + - /observability-plugin/ppl --- -# Piped Processing Language +# PPL - Piped Processing Language Piped Processing Language (PPL) is a query language that lets you use pipe (`|`) syntax to explore, discover, and query data stored in OpenSearch. @@ -42,7 +45,7 @@ Go to **Query Workbench** and select **PPL**. The following example returns `firstname` and `lastname` fields for documents in an `accounts` index with `age` greater than 18: -```json +```sql search source=accounts | where age > 18 | fields firstname, lastname diff --git a/_search-plugins/sql/ppl/syntax.md b/_search-plugins/sql/ppl/syntax.md new file mode 100644 index 00000000000..7d57e3e6dee --- /dev/null +++ b/_search-plugins/sql/ppl/syntax.md @@ -0,0 +1,70 @@ +--- +layout: default +title: Syntax +parent: PPL - Piped Processing Language +grand_parent: SQL Plugin - SQL & PPL +nav_order: 1 +--- + +# PPL Syntax + +Every PPL query begins with the `search` command. It specifies the index to search and retrieve documents from. Subsequent commands can follow in any order. + +**NOTE:** At the moment `PPL` supports only one `search` command and it can be omitted to simplify the query. + + +## Syntax + +```sql +search source= [boolean-expression] +source= [boolean-expression] +``` + +Field | Description | Required +:--- | :--- |:--- +`search` | Specify search keywords. | Yes +`index` | Specify which index to query from. | No +`bool-expression` | Specify an expression that evaluates to a boolean value. | No + +## Examples + +In the following example, the `search` command refers to an `accounts` index as the source, then uses `fields` and `where` commands for the conditions: + +```sql +search source=accounts +| where age > 18 +| fields firstname, lastname +``` + +In the following examples, angle brackets `< >` enclose required arguments and square brackets `[ ]` enclose optional arguments. + +{: .note } + + +*Example 2*: Get all documents + +To get all documents from the `accounts` index: + +```sql +search source=accounts; +``` + +| account_number | firstname | address | balance | gender | city | employer | state | age | email | lastname | +:--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- +| 1 | Amber | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com | Duke +| 6 | Hattie | 671 Bristol Street | 5686 | M | Dante | Netagy | TN | 36 | hattiebond@netagy.com | Bond +| 13 | Nanette | 789 Madison Street | 32838 | F | Nogal | Quility | VA | 28 | null | Bates +| 18 | Dale | 467 Hutchinson Court | 4180 | M | Orick | null | MD | 33 | daleadams@boink.com | Adams + +*Example 3*: Get documents that match a condition + +To get all documents from the `accounts` index that have either `account_number` equal to 1 or have `gender` as `F`: + +```sql +search source=accounts account_number=1 or gender=\"F\"; +``` + +| account_number | firstname | address | balance | gender | city | employer | state | age | email | lastname | +:--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- +| 1 | Amber | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com | Duke | +| 13 | Nanette | 789 Madison Street | 32838 | F | Nogal | Quility | VA | 28 | null | Bates | diff --git a/_search-plugins/sql/protocol.md b/_search-plugins/sql/protocol.md index 1c62308513d..199f34337f9 100644 --- a/_search-plugins/sql/protocol.md +++ b/_search-plugins/sql/protocol.md @@ -1,8 +1,8 @@ --- layout: default title: Protocol -parent: SQL -nav_order: 14 +parent: SQL Plugin - SQL & PPL +nav_order: 2 --- # Protocol @@ -329,3 +329,74 @@ Amber|Duke|32 Dale|Adams|33 Hattie|Bond|36 ``` + +## JDBC Format + +### Description + +The plugin provides responses in JDBC format. The JDBC format is widely used because it provides schema information and more functionality such as pagination. Besides JDBC driver, various clients can benefit from the detailed and well formatted response. + +**NOTE:** `JDBC` is the only format supported by the `PPL` endpoint, but it is one of several formats supported by the `SQL` endpoint. + +### Example + +The body of HTTP POST request with the PPL query: + +```console +>> curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl?format=jdbc -d '{ + "query" : "source=accounts | fields firstname, lastname" +}' +``` + +The following example shows a normal response where the schema includes a field name and its type and datarows includes the result set: + +```json +{ + "schema": [ + { + "name": "firstname", + "type": "string" + }, + { + "name": "lastname", + "type": "string" + } + ], + "datarows": [ + [ + "Amber", + "Duke" + ], + [ + "Hattie", + "Bond" + ], + [ + "Nanette", + "Bates" + ], + [ + "Dale", + "Adams" + ] + ], + "total": 4, + "size": 4 +} +``` + +If any error occurred, error message and the cause will be returned instead: + +```console +curl -H 'Content-Type: application/json' -X POST localhost:9200/_plugins/_ppl -d '{ + "query" : "source=unknown | fields firstname, lastname" +}' +{ + "error": { + "reason": "Error occurred in OpenSearch engine: no such index [unknown]", + "details": "org.opensearch.index.IndexNotFoundException: no such index [unknown]\nFor more details, please send request for Json format to see the raw response from opensearch engine.", + "type": "IndexNotFoundException" + }, + "status": 404 +} +``` \ No newline at end of file diff --git a/_search-plugins/sql/settings.md b/_search-plugins/sql/settings.md index 93832a8cd89..3c142213749 100644 --- a/_search-plugins/sql/settings.md +++ b/_search-plugins/sql/settings.md @@ -1,13 +1,13 @@ --- layout: default title: Settings -parent: SQL -nav_order: 16 +parent: SQL Plugin - SQL & PPL +nav_order: 77 --- # Settings -The SQL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster. +The SQL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster. It is possible to independently disable processing of `PPL` or `SQL` queries. You can update these settings like any other cluster setting: @@ -20,7 +20,23 @@ PUT _cluster/settings } ``` +There is another format of request which could be used: + +```json +PUT _cluster/settings +{ + "transient": { + "plugins": { + "ppl": { + "enabled": "false" + } + } + } +} +``` + Similarly, you can also update the settings by sending the request to the plugin setting endpoint `_plugins/_query/setting`: + ```json PUT _plugins/_query/settings { @@ -30,9 +46,29 @@ PUT _plugins/_query/settings } ``` +Or in alternative format: + +```json +PUT _plugins/_query/settings +{ + "transient": { + "plugins": { + "ppl": { + "enabled": "false" + } + } + } +} +``` + +**Note**: Requests to `_plugins/_ppl` and `_plugins/_sql` endpoints include index names in the request body, so they have the same access policy considerations as the `bulk`, `mget`, and `msearch` operations. Seting the `rest.action.multi.allow_explicit_index` parameter to `false`, disables both `SQL` and `PPL` endpoints. + +# Available settings + Setting | Default | Description :--- | :--- | :--- -`plugins.sql.enabled` | True | Change to `false` to disable the plugin. +`plugins.sql.enabled` | True | Change to `false` to disable the `SQL` support in the plugin. +`plugins.ppl.enabled` | True | Change to `false` to disable the `PPL` component. `plugins.sql.slowlog` | 2 seconds | Configure the time limit (in seconds) for slow queries. The plugin logs slow queries as `Slow query: elapsed=xxx (ms)` in `opensearch.log`. `plugins.sql.cursor.keep_alive` | 1 minute | This value configures how long the cursor context is kept open. Cursor contexts are resource heavy, so we recommend a low value. `plugins.query.memory_limit` | 85% | This setting configures the heap memory usage limit for the circuit breaker of the query engine. diff --git a/_search-plugins/sql/sql-full-text.md b/_search-plugins/sql/sql-full-text.md deleted file mode 100644 index 641fd27d6bb..00000000000 --- a/_search-plugins/sql/sql-full-text.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -layout: default -title: Full-Text Search -parent: SQL -nav_order: 8 ---- - -# Full-text search - -Use SQL commands for full-text search. The SQL plugin supports a subset of the full-text queries available in OpenSearch. - -To learn about full-text queries in OpenSearch, see [Full-text queries]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/). - -## Match - -Use the `match` command to search documents that match a `string`, `number`, `date`, or `boolean` value for a given field. - -### Syntax - -```sql -match(field_expression, query_expression[, option=]*) -``` - -You can specify the following options: - -- `analyzer` -- `auto_generate_synonyms_phrase` -- `fuzziness` -- `max_expansions` -- `prefix_length` -- `fuzzy_transpositions` -- `fuzzy_rewrite` -- `lenient` -- `operator` -- `minimum_should_match` -- `zero_terms_query` -- `boost` - -*Example 1*: Search the `message` field: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": "this is a test" - } - } -} -``` - -SQL query: - -```sql -SELECT message FROM my_index WHERE match(message, "this is a test") -``` - -*Example 2*: Search the `message` field with the `operator` parameter: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": { - "query": "this is a test", - "operator": "and" - } - } - } -} -``` - -SQL query: - -```sql -SELECT message FROM my_index WHERE match(message, "this is a test", operator=and) -``` - -*Example 3*: Search the `message` field with the `operator` and `zero_terms_query` parameters: - -```json -GET my_index/_search -{ - "query": { - "match": { - "message": { - "query": "to be or not to be", - "operator": "and", - "zero_terms_query": "all" - } - } - } -} -``` - -SQL query: - -```sql -SELECT message FROM my_index WHERE match(message, "this is a test", operator=and, zero_terms_query=all) -``` - -To search for text in a single field, use `MATCHQUERY` or `MATCH_QUERY` functions. - -Pass in your search query and the field name that you want to search against. - -```sql -SELECT account_number, address -FROM accounts -WHERE MATCH_QUERY(address, 'Holmes') -``` - -Alternate syntax: - -```sql -SELECT account_number, address -FROM accounts -WHERE address = MATCH_QUERY('Holmes') -``` - - -| account_number | address -:--- | :--- -1 | 880 Holmes Lane - - -## Multi match - -To search for text in multiple fields, use `MULTI_MATCH`, `MULTIMATCH`, or `MULTIMATCHQUERY` functions. - -For example, search for `Dale` in either the `firstname` or `lastname` fields: - - -```sql -SELECT firstname, lastname -FROM accounts -WHERE MULTI_MATCH('query'='Dale', 'fields'='*name') -``` - - -| firstname | lastname -:--- | :--- -Dale | Adams - - -## Query string - -To split text based on operators, use the `QUERY` function. - - -```sql -SELECT account_number, address -FROM accounts -WHERE QUERY('address:Lane OR address:Street') -``` - - -| account_number | address -:--- | :--- -1 | 880 Holmes Lane -6 | 671 Bristol Street -13 | 789 Madison Street - - -The `QUERY` function supports logical connectives, wildcard, regex, and proximity search. - - -## Match phrase - -To search for exact phrases, use `MATCHPHRASE`, `MATCH_PHRASE`, or `MATCHPHRASEQUERY` functions. - - -```sql -SELECT account_number, address -FROM accounts -WHERE MATCH_PHRASE(address, '880 Holmes Lane') -``` - - -| account_number | address -:--- | :--- -1 | 880 Holmes Lane - - -## Score query - -To return a relevance score along with every matching document, use `SCORE`, `SCOREQUERY`, or `SCORE_QUERY` functions. - -You need to pass in two arguments. The first is the `MATCH_QUERY` expression. The second is an optional floating point number to boost the score (default value is 1.0). - - -```sql -SELECT account_number, address, _score -FROM accounts -WHERE SCORE(MATCH_QUERY(address, 'Lane'), 0.5) OR - SCORE(MATCH_QUERY(address, 'Street'), 100) -ORDER BY _score -``` - - -| account_number | address | score -:--- | :--- | :--- -1 | 880 Holmes Lane | 0.5 -6 | 671 Bristol Street | 100 -13 | 789 Madison Street | 100 diff --git a/_search-plugins/sql/aggregations.md b/_search-plugins/sql/sql/aggregations.md similarity index 98% rename from _search-plugins/sql/aggregations.md rename to _search-plugins/sql/sql/aggregations.md index 688ec1b9620..1b7e0108efd 100644 --- a/_search-plugins/sql/aggregations.md +++ b/_search-plugins/sql/sql/aggregations.md @@ -2,6 +2,7 @@ layout: default title: Aggregation Functions parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 11 --- diff --git a/_search-plugins/sql/basic.md b/_search-plugins/sql/sql/basic.md similarity index 99% rename from _search-plugins/sql/basic.md rename to _search-plugins/sql/sql/basic.md index 967ef6d3cde..aabe809b7e1 100644 --- a/_search-plugins/sql/basic.md +++ b/_search-plugins/sql/sql/basic.md @@ -2,6 +2,7 @@ layout: default title: Basic Queries parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 5 --- diff --git a/_search-plugins/sql/complex.md b/_search-plugins/sql/sql/complex.md similarity index 99% rename from _search-plugins/sql/complex.md rename to _search-plugins/sql/sql/complex.md index 70a69bbd407..7e15c33500d 100644 --- a/_search-plugins/sql/complex.md +++ b/_search-plugins/sql/sql/complex.md @@ -2,6 +2,7 @@ layout: default title: Complex Queries parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 6 --- diff --git a/_search-plugins/sql/delete.md b/_search-plugins/sql/sql/delete.md similarity index 97% rename from _search-plugins/sql/delete.md rename to _search-plugins/sql/sql/delete.md index 397c47ed472..fec97bb4929 100644 --- a/_search-plugins/sql/delete.md +++ b/_search-plugins/sql/sql/delete.md @@ -2,6 +2,7 @@ layout: default title: Delete parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 12 --- diff --git a/_search-plugins/sql/sql/functions.md b/_search-plugins/sql/sql/functions.md new file mode 100755 index 00000000000..446abac0665 --- /dev/null +++ b/_search-plugins/sql/sql/functions.md @@ -0,0 +1,202 @@ +--- +layout: default +title: Functions +parent: SQL +grand_parent: SQL Plugin - SQL & PPL +nav_order: 7 +--- + +# Functions + +`SQL` language supports all SQL plugin [functions]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/), including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few function synonyms which are available in `SQL` only. +These synonyms are provided by `V1` engine, please see [limitations page]({{site.url}}{{site.baseurl}}/search-plugins/sql/limitation) for more info about it. + +## Match query + +`MATCHQUERY` and `MATCH_QUERY` are synonyms for [`MATCH`]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text#match) relevance function. They don't accept additional arguments, but provide an alternate syntax. + +### Syntax + +Pass in your search query and the field name that you want to search against. + +```sql +match_query(field_expression, query_expression[, option=]*) +matchquery(field_expression, query_expression[, option=]*) +field_expression = match_query(query_expression[, option=]*) +field_expression = matchquery(query_expression[, option=]*) +``` + +You can specify the following options in any order: + +- `analyzer` +- `boost` + +### Example + +```sql +SELECT account_number, address +FROM accounts +WHERE MATCHQUERY(address, 'Holmes') +``` + +Alternate syntax: + +```sql +SELECT account_number, address +FROM accounts +WHERE address = MATCH_QUERY('Holmes') +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane + +## Multi match + +There are 3 synonyms for [`MULTI_MATCH`]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text#multi-match) which have slightly different syntax. They accept query string and fields list with weights, and accept additional parameters. + +### Syntax + +```sql +multimatch('query'=query_expression[, 'fields'=field_expression][, option=]*) +multi_match('query'=query_expression[, 'fields'=field_expression][, option=]*) +multimatchquery('query'=query_expression[, 'fields'=field_expression][, option=]*) +``` + +`fields` is optional parameter, it could be a single field or a comma-separated list; whitespaces are not allowed there. The weight is optional and is specified after the field name. It should be delimited by the `caret` character -- `^` -- without whitespaces. Please, refer to examples below: + +```sql +multi_match('fields' = "Tags^2,Title^3.4,Body,Comments^0.3", ...) +multi_match('fields' = "Title", ...) +``` + +You can specify the following options in any order: + +- `analyzer` +- `boost` +- `slop` +- `type` +- `tie_breaker` +- `operator` + +## Query string + +`QUERY` is a [`QUERY_STRING`]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text#query-string) synonym. + +### Syntax + +```sql +query('query'=query_expression[, 'fields'=field_expression][, option=]*) +``` + +`fields` is optional parameter, it could be a single field or a comma-separated list; whitespaces are not allowed there. The weight is optional and is specified after the field name. It should be delimited by the `caret` character -- `^` -- without whitespaces. Please, refer to examples below: + +```sql +query('fields' = "Tags^2,Title^3.4,Body,Comments^0.3", ...) +query('fields' = "Tags", ...) +``` + +You can specify the following options in any order: + +- `analyzer` +- `boost` +- `slop` +- `default_field` + +### Example of using `query_string` in SQL and PPL queries: + +The REST API search request +```json +GET accounts/_search +{ + "query": { + "query_string": { + "query": "Lane Street", + "fields": [ "address" ], + } + } +} +``` + +could be called using `query` function + +```sql +SELECT account_number, address +FROM accounts +WHERE query('address:Lane OR address:Street') +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane +6 | 671 Bristol Street +13 | 789 Madison Street + +## Match phrase + +`MATCHPHRASEQUERY` is a [`MATCH_PHRASE`]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text#query-string) synonym. + +### Syntax + +```sql +matchphrasequery(query_expression, field_expression[, option=]*) +``` + +You can specify the following options in any order: + +- `analyzer` +- `boost` +- `slop` + +## Score query + +To return a relevance score along with every matching document, use `SCORE`, `SCOREQUERY`, or `SCORE_QUERY` functions. + +### Syntax + +`SCORE` expects two arguments. The first is the [`MATCH_QUERY`](#match-query) expression. The second is an optional floating point number to boost the score (default value is 1.0). + +```sql +SCORE(match_query_expression, score) +SCOREQUERY(match_query_expression, score) +SCORE_QUERY(match_query_expression, score) +``` + +### Example + +```sql +SELECT account_number, address, _score +FROM accounts +WHERE SCORE(MATCH_QUERY(address, 'Lane'), 0.5) OR + SCORE(MATCH_QUERY(address, 'Street'), 100) +ORDER BY _score +``` + +| account_number | address | score +:--- | :--- | :--- +1 | 880 Holmes Lane | 0.5 +6 | 671 Bristol Street | 100 +13 | 789 Madison Street | 100 + +## Wildcard query + +To search documents by given wildcard use `WILDCARDQUERY` or `WILDCARD_QUERY` functions. + +### Syntax + +```sql +wildcardquery(field_expression, query_expression[, boost=]) +wildcard_query(field_expression, query_expression[, boost=]) +``` + +### Example + +```sql +SELECT account_number, address +FROM accounts +WHERE wildcard_query(address, '*Holmes*'); +``` + +| account_number | address +:--- | :--- +1 | 880 Holmes Lane diff --git a/_search-plugins/sql/sql/index.md b/_search-plugins/sql/sql/index.md new file mode 100644 index 00000000000..eee4336a070 --- /dev/null +++ b/_search-plugins/sql/sql/index.md @@ -0,0 +1,68 @@ +--- +layout: default +title: SQL +parent: SQL Plugin - SQL & PPL +nav_order: 4 +has_children: true +redirect_from: + - /search-plugins/sql/sql +--- + +# SQL + +## Workbench + +The easiest way to get familiar with the SQL plugin is to use **Query Workbench** in OpenSearch Dashboards to test various queries. To learn more, see [Workbench]({{site.url}}{{site.baseurl}}/search-plugins/sql/workbench/). + +![OpenSearch Dashboards SQL UI plugin]({{site.url}}{{site.baseurl}}/images/sql.png) + + +## REST API + +To use the SQL plugin with your own applications, send requests to `_plugins/_sql`: + +```json +POST _plugins/_sql +{ + "query": "SELECT * FROM my-index LIMIT 50" +} +``` + +Here’s how core SQL concepts map to OpenSearch: + +SQL | OpenSearch +:--- | :--- +Table | Index +Row | Document +Column | Field + +You can query multiple indices by listing them or using wildcards: + +```json +POST _plugins/_sql +{ + "query": "SELECT * FROM my-index1,myindex2,myindex3 LIMIT 50" +} + +POST _plugins/_sql +{ + "query": "SELECT * FROM my-index* LIMIT 50" +} +``` + +For a sample [curl](https://curl.haxx.se/) command, try: + +```bash +curl -XPOST https://localhost:9200/_plugins/_sql -u 'admin:admin' -k -H 'Content-Type: application/json' -d '{"query": "SELECT * FROM opensearch_dashboards_sample_data_flights LIMIT 10"}' +``` + +By default, queries return data in JDBC format, but you can also return data in standard OpenSearch JSON, CSV, or raw formats: + +```json +POST _plugins/_sql?format=json|csv|raw +{ + "query": "SELECT * FROM my-index LIMIT 50" +} +``` + +See the rest of this guide for detailed information on request parameters, settings, supported operations, tools, and more. diff --git a/_search-plugins/sql/jdbc.md b/_search-plugins/sql/sql/jdbc.md similarity index 63% rename from _search-plugins/sql/jdbc.md rename to _search-plugins/sql/sql/jdbc.md index fa9c80d2e2d..80c3ab81289 100644 --- a/_search-plugins/sql/jdbc.md +++ b/_search-plugins/sql/sql/jdbc.md @@ -2,6 +2,7 @@ layout: default title: JDBC Driver parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 71 --- @@ -10,3 +11,7 @@ nav_order: 71 The Java Database Connectivity (JDBC) driver lets you integrate OpenSearch with your favorite business intelligence (BI) applications. For information on downloading and using the JAR file, see [the SQL repository on GitHub](https://github.com/opensearch-project/sql/tree/master/sql-jdbc). + +## Connecting to Tableau + +Follow detailed instructions on the [GitHub repository](https://github.com/opensearch-project/sql/blob/main/bi-connectors/TableauConnector/README.md). diff --git a/_search-plugins/sql/metadata.md b/_search-plugins/sql/sql/metadata.md similarity index 99% rename from _search-plugins/sql/metadata.md rename to _search-plugins/sql/sql/metadata.md index 5ba108e480c..3e939491f95 100644 --- a/_search-plugins/sql/metadata.md +++ b/_search-plugins/sql/sql/metadata.md @@ -2,6 +2,7 @@ layout: default title: Metadata Queries parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 9 --- diff --git a/_search-plugins/sql/odbc.md b/_search-plugins/sql/sql/odbc.md similarity index 78% rename from _search-plugins/sql/odbc.md rename to _search-plugins/sql/sql/odbc.md index 4cfee69ca59..5ad51624426 100644 --- a/_search-plugins/sql/odbc.md +++ b/_search-plugins/sql/sql/odbc.md @@ -2,6 +2,7 @@ layout: default title: ODBC Driver parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 72 --- @@ -9,9 +10,7 @@ nav_order: 72 The Open Database Connectivity (ODBC) driver is a read-only ODBC driver for Windows and macOS that lets you connect business intelligence (BI) and data visualization applications like [Tableau](https://github.com/opensearch-project/sql/blob/main/sql-odbc/docs/user/tableau_support.md), [Microsoft Excel](https://github.com/opensearch-project/sql/blob/main/sql-odbc/docs/user/microsoft_excel_support.md), and [Power BI](https://github.com/opensearch-project/sql/blob/main/sql-odbc/docs/user/power_bi_support.md) to the SQL plugin. -For information on downloading and using the JAR file, see [the SQL repository on GitHub](https://github.com/opensearch-project/sql/tree/main/sql-odbc). - -{% comment %} +For information on downloading and using the driver, see [the SQL repository on GitHub](https://github.com/opensearch-project/sql/tree/main/sql-odbc). ## Specifications @@ -23,8 +22,8 @@ The following operating systems are supported: Operating System | Version :--- | :--- -Windows | Windows 10 -macOS | Catalina 10.15.4 and Mojave 10.14.6 +Windows | Windows 10, Windows 11 +macOS | Catalina 10.15.4, Mojave 10.14.6, Big Sur 11.6.7, Monterey 12.4 ## Concepts @@ -46,13 +45,13 @@ To install the driver, download the bundled distribution installer from [here](h The installer is unsigned and shows a security dialog. Choose **More info** and **Run anyway**. -1. Choose **Next** to proceed with the installation. +2. Choose **Next** to proceed with the installation. -1. Accept the agreement, and choose **Next**. +3. Accept the agreement, and choose **Next**. -1. The installer comes bundled with documentation and useful resources files to connect with various BI tools (for example, a `.tdc` file for Tableau). You can choose to keep or remove these resources. Choose **Next**. +4. The installer comes bundled with documentation and useful resources files to connect with various BI tools (for example, a `.tdc` file for Tableau). You can choose to keep or remove these resources. Choose **Next**. -1. Choose **Install** and **Finish**. +5. Choose **Install** and **Finish**. The following connection information is set up as part of the default DSN: @@ -73,13 +72,13 @@ Before installing the ODBC Driver on macOS, install the iODBC Driver Manager. The installer is unsigned and shows a security dialog. Right-click on the installer and choose **Open**. -1. Choose **Continue** several times to proceed with the installation. +2. Choose **Continue** several times to proceed with the installation. -1. Choose the **Destination** to install the driver files. +3. Choose the **Destination** to install the driver files. -1. The installer comes bundled with documentation and useful resources files to connect with various BI tools (for example, a `.tdc` file for Tableau). You can choose to keep or remove these resources. Choose **Continue**. +4. The installer comes bundled with documentation and useful resources files to connect with various BI tools (for example, a `.tdc` file for Tableau). You can choose to keep or remove these resources. Choose **Continue**. -1. Choose **Install** and **Close**. +5. Choose **Install** and **Close**. Currently, the DSN is not set up as part of the installation and needs to be configured manually. First, open `iODBC Administrator`: @@ -90,19 +89,19 @@ sudo /Applications/iODBC/iODBC\ Administrator64.app/Contents/MacOS/iODBC\ Admini This command gives the application permissions to save the driver and DSN configurations. 1. Choose **ODBC Drivers** tab. -1. Choose **Add a Driver** and fill in the following details: +2. Choose **Add a Driver** and fill in the following details: - **Description of the Driver**: Enter the driver name that you used for the ODBC connection (for example, OpenSearch SQL ODBC Driver). - **Driver File Name**: Enter the path to the driver file (default: `/bin/libopensearchsqlodbc.dylib`). - **Setup File Name**: Enter the path to the setup file (default: `/bin/libopensearchsqlodbc.dylib`). -1. Choose the user driver. -1. Choose **OK** to save the options. -1. Choose the **User DSN** tab. -1. Select **Add**. -1. Choose the driver that you added above. -1. For **Data Source Name (DSN)**, enter the name of the DSN used to store connection options (for example, OpenSearch SQL ODBC DSN). -1. For **Comment**, add an optional comment. -1. Add key-value pairs by using the `+` button. We recommend the following options for a default local OpenSearch installation: +3. Choose the user driver. +4. Choose **OK** to save the options. +5. Choose the **User DSN** tab. +6. Select **Add**. +7. Choose the driver that you added above. +8. For **Data Source Name (DSN)**, enter the name of the DSN used to store connection options (for example, OpenSearch SQL ODBC DSN). +9. For **Comment**, add an optional comment. +10. Add key-value pairs by using the `+` button. We recommend the following options for a default local OpenSearch installation: - **Host**: `localhost` - OpenSearch server endpoint - **Port**: `9200` - The server port - **Auth**: `NONE` - The authentication mode @@ -111,8 +110,8 @@ This command gives the application permissions to save the driver and DSN config - **ResponseTimeout**: `10` - The number of seconds to wait for a response from the server - **UseSSL**: `0` - Do not use SSL for connections -1. Choose **OK** to save the DSN configuration. -1. Choose **OK** to exit the iODBC Administrator. +11. Choose **OK** to save the DSN configuration. +12. Choose **OK** to exit the iODBC Administrator. ## Customizing the ODBC driver @@ -166,13 +165,12 @@ Option | Description | Type | Default Option | Description | Type | Default :--- | :--- -`LogLevel` | Severity level for driver logs. | one of `ES_OFF`, `ES_FATAL`, `ES_ERROR`, `ES_INFO`, `ES_DEBUG`, `ES_TRACE`, `ES_ALL` | `ES_WARNING` +`LogLevel` | Severity level for driver logs. | one of `LOG_OFF`, `LOG_FATAL`, `LOG_ERROR`, `LOG_INFO`, `LOG_DEBUG`, `LOG_TRACE`, `LOG_ALL` | `LOG_WARNING` `LogOutput` | Location for storing driver logs. | `string` | `WIN: C:\`, `MAC: /tmp` You need administrative privileges to change the logging options. {: .note } - ## Connecting to Tableau Pre-requisites: @@ -183,13 +181,14 @@ Pre-requisites: 1. Start Tableau. Under the **Connect** section, go to **To a Server** and choose **Other Databases (ODBC)**. -1. In the **DSN drop-down**, select the OpenSearch DSN you set up in the previous set of steps. The options you added will be automatically filled into the **Connection Attributes**. +2. In the **DSN drop-down**, select the OpenSearch DSN you set up in the previous set of steps. The options you added will be automatically filled into the **Connection Attributes**. -1. Select **Sign In**. After a few seconds, Tableau connects to your OpenSearch server. Once connected, you will directed to **Datasource** window. The **Database** will be already populated with name of the OpenSearch cluster. +3. Select **Sign In**. After a few seconds, Tableau connects to your OpenSearch server. Once connected, you will directed to **Datasource** window. The **Database** will be already populated with name of the OpenSearch cluster. To list all the indices, click the search icon under **Table**. -1. Start playing with data by dragging table to connection area. Choose **Update Now** or **Automatically Update** to populate table data. +4. Start playing with data by dragging table to connection area. Choose **Update Now** or **Automatically Update** to populate table data. +See more detailed instructions on the [GitHub repository](https://github.com/opensearch-project/sql/blob/main/sql-odbc/docs/user/tableau_support.md). ### Troubleshooting @@ -203,4 +202,6 @@ This is most likely due to OpenSearch server not running on **host** and **post* Confirm **host** and **post** are correct and OpenSearch server is running with OpenSearch SQL plugin. Also make sure `.tdc` that was downloaded with the installer is copied correctly to `/Documents/My Tableau Repository/Datasources` directory. -{% endcomment %} +## Connecting to Microsoft Power BI + +Follow [installation instructions](https://github.com/opensearch-project/sql/blob/main/bi-connectors/PowerBIConnector/README.md) and [configuration instructions](https://github.com/opensearch-project/sql/blob/main/bi-connectors/PowerBIConnector/power_bi_support.md) published on the GitHub repostiry. diff --git a/_search-plugins/sql/partiql.md b/_search-plugins/sql/sql/partiql.md similarity index 99% rename from _search-plugins/sql/partiql.md rename to _search-plugins/sql/sql/partiql.md index 1dfadb817da..fe7b0d54643 100644 --- a/_search-plugins/sql/partiql.md +++ b/_search-plugins/sql/sql/partiql.md @@ -2,7 +2,8 @@ layout: default title: JSON Support parent: SQL -nav_order: 7 +grand_parent: SQL Plugin - SQL & PPL +nav_order: 8 --- # JSON Support diff --git a/_search-plugins/sql/troubleshoot.md b/_search-plugins/sql/troubleshoot.md index d2d16f633f1..a66009ccf8a 100644 --- a/_search-plugins/sql/troubleshoot.md +++ b/_search-plugins/sql/troubleshoot.md @@ -1,8 +1,8 @@ --- layout: default title: Troubleshooting -parent: SQL -nav_order: 17 +parent: SQL Plugin - SQL & PPL +nav_order: 88 --- # Troubleshooting diff --git a/_search-plugins/sql/workbench.md b/_search-plugins/sql/workbench.md index 18d593f3b4e..8c09a177da3 100644 --- a/_search-plugins/sql/workbench.md +++ b/_search-plugins/sql/workbench.md @@ -2,6 +2,7 @@ layout: default title: Query Workbench parent: SQL +grand_parent: SQL Plugin - SQL & PPL nav_order: 1 --- From d5e9d0ddcfdfb8a52250205bdf9ba7a60b17cc9a Mon Sep 17 00:00:00 2001 From: Yury Fridlyand Date: Tue, 9 Aug 2022 15:25:01 -0700 Subject: [PATCH 2/3] Address PR feedback. Signed-off-by: Yury Fridlyand --- _search-plugins/sql/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_search-plugins/sql/cli.md b/_search-plugins/sql/cli.md index 00d4e48fc59..a5fd9a336c8 100644 --- a/_search-plugins/sql/cli.md +++ b/_search-plugins/sql/cli.md @@ -62,7 +62,7 @@ For a list of all available configurations, see [clirc](https://github.com/opens ## Using the CLI -1. Run the CLI tool. If you cluster runs with default security settings, use following command line: +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 ``` From cfd9164bc3898c85c2a8d4884cd6f7c879bb30d7 Mon Sep 17 00:00:00 2001 From: Yury Fridlyand Date: Wed, 17 Aug 2022 10:00:53 -0700 Subject: [PATCH 3/3] Address PR feedback by @joshuali925. Signed-off-by: Yury Fridlyand --- _search-plugins/sql/cli.md | 2 +- _search-plugins/sql/datatypes.md | 2 +- _search-plugins/sql/endpoints.md | 2 +- _search-plugins/sql/full-text.md | 2 +- _search-plugins/sql/functions.md | 4 ++-- _search-plugins/sql/identifiers.md | 2 +- _search-plugins/sql/index.md | 4 ++-- _search-plugins/sql/limitation.md | 2 +- _search-plugins/sql/monitoring.md | 2 +- _search-plugins/sql/ppl/functions.md | 8 ++++---- _search-plugins/sql/ppl/index.md | 2 +- _search-plugins/sql/ppl/syntax.md | 2 +- _search-plugins/sql/protocol.md | 2 +- _search-plugins/sql/settings.md | 2 +- _search-plugins/sql/sql/aggregations.md | 2 +- _search-plugins/sql/sql/basic.md | 2 +- _search-plugins/sql/sql/complex.md | 2 +- _search-plugins/sql/sql/delete.md | 2 +- _search-plugins/sql/sql/functions.md | 4 ++-- _search-plugins/sql/sql/index.md | 2 +- _search-plugins/sql/sql/jdbc.md | 2 +- _search-plugins/sql/sql/metadata.md | 2 +- _search-plugins/sql/sql/odbc.md | 2 +- _search-plugins/sql/sql/partiql.md | 2 +- _search-plugins/sql/troubleshoot.md | 2 +- _search-plugins/sql/workbench.md | 2 +- 26 files changed, 32 insertions(+), 32 deletions(-) diff --git a/_search-plugins/sql/cli.md b/_search-plugins/sql/cli.md index a5fd9a336c8..96fa800f244 100644 --- a/_search-plugins/sql/cli.md +++ b/_search-plugins/sql/cli.md @@ -1,7 +1,7 @@ --- layout: default title: SQL & PPL CLI -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 3 --- diff --git a/_search-plugins/sql/datatypes.md b/_search-plugins/sql/datatypes.md index 1edff1d4c7c..1de6c570f0d 100644 --- a/_search-plugins/sql/datatypes.md +++ b/_search-plugins/sql/datatypes.md @@ -1,7 +1,7 @@ --- layout: default title: Data Types -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 7 --- diff --git a/_search-plugins/sql/endpoints.md b/_search-plugins/sql/endpoints.md index 6a912a403d8..ba1c6c87e97 100644 --- a/_search-plugins/sql/endpoints.md +++ b/_search-plugins/sql/endpoints.md @@ -1,7 +1,7 @@ --- layout: default title: Endpoint -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 1 --- diff --git a/_search-plugins/sql/full-text.md b/_search-plugins/sql/full-text.md index c772f01ba46..226ad693112 100644 --- a/_search-plugins/sql/full-text.md +++ b/_search-plugins/sql/full-text.md @@ -1,7 +1,7 @@ --- layout: default title: Full-Text Search -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 11 --- diff --git a/_search-plugins/sql/functions.md b/_search-plugins/sql/functions.md index c96fd0776e2..ebe079a751e 100644 --- a/_search-plugins/sql/functions.md +++ b/_search-plugins/sql/functions.md @@ -1,7 +1,7 @@ --- layout: default title: Functions -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 10 --- @@ -12,7 +12,7 @@ You must enable fielddata in the document mapping for most string functions to w The specification shows the return type of the function with a generic type `T` as the argument. For example, `abs(number T) -> T` means that the function `abs` accepts a numerical argument of type `T`, which could be any sub-type of the `number` type, and it returns the actual type of `T` as the return type. -The SQL plugin supports the following functions. +The SQL plugin supports the following common functions shared across `SQL` and `PPL` languages. ## Mathematical diff --git a/_search-plugins/sql/identifiers.md b/_search-plugins/sql/identifiers.md index 447e7645f56..e3e1a64ff25 100644 --- a/_search-plugins/sql/identifiers.md +++ b/_search-plugins/sql/identifiers.md @@ -1,7 +1,7 @@ --- layout: default title: Identifiers -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 6 --- diff --git a/_search-plugins/sql/index.md b/_search-plugins/sql/index.md index 4a0e4e4d8da..1a1ac297f73 100644 --- a/_search-plugins/sql/index.md +++ b/_search-plugins/sql/index.md @@ -1,6 +1,6 @@ --- layout: default -title: SQL Plugin - SQL & PPL +title: SQL & PPL nav_order: 38 has_children: true has_toc: false @@ -8,7 +8,7 @@ redirect_from: - /search-plugins/sql/ --- -# SQL Plugin - SQL & PPL +# SQL & PPL OpenSearch SQL lets you write queries in SQL rather than the [OpenSearch query domain-specific language (DSL)]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text). If you're already familiar with SQL and don't want to learn the query DSL, this feature is a great option. diff --git a/_search-plugins/sql/limitation.md b/_search-plugins/sql/limitation.md index 6e825f1361e..6f4d8f884ce 100644 --- a/_search-plugins/sql/limitation.md +++ b/_search-plugins/sql/limitation.md @@ -1,7 +1,7 @@ --- layout: default title: Limitations -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 99 --- diff --git a/_search-plugins/sql/monitoring.md b/_search-plugins/sql/monitoring.md index 78de378b902..9a19bf45f94 100644 --- a/_search-plugins/sql/monitoring.md +++ b/_search-plugins/sql/monitoring.md @@ -1,7 +1,7 @@ --- layout: default title: Monitoring -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 95 --- diff --git a/_search-plugins/sql/ppl/functions.md b/_search-plugins/sql/ppl/functions.md index 1ed462440df..f78e493b37d 100644 --- a/_search-plugins/sql/ppl/functions.md +++ b/_search-plugins/sql/ppl/functions.md @@ -1,14 +1,14 @@ --- layout: default -title: Functions +title: Commands parent: PPL - Piped Processing Language -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 2 --- -# Functions +# Commands -`PPL` supports all [`SQL`]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/) functions, including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few more functions which are available in `PPL` only. +`PPL` supports all [`SQL` common]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/) functions, including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few more functions (called `commands`) which are available in `PPL` only. ## dedup diff --git a/_search-plugins/sql/ppl/index.md b/_search-plugins/sql/ppl/index.md index 6c2d49a6713..0b811b0923c 100644 --- a/_search-plugins/sql/ppl/index.md +++ b/_search-plugins/sql/ppl/index.md @@ -1,7 +1,7 @@ --- layout: default title: PPL - Piped Processing Language -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 5 has_children: true has_toc: false diff --git a/_search-plugins/sql/ppl/syntax.md b/_search-plugins/sql/ppl/syntax.md index 7d57e3e6dee..5e57b56f4f3 100644 --- a/_search-plugins/sql/ppl/syntax.md +++ b/_search-plugins/sql/ppl/syntax.md @@ -2,7 +2,7 @@ layout: default title: Syntax parent: PPL - Piped Processing Language -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 1 --- diff --git a/_search-plugins/sql/protocol.md b/_search-plugins/sql/protocol.md index 199f34337f9..8e245ef5256 100644 --- a/_search-plugins/sql/protocol.md +++ b/_search-plugins/sql/protocol.md @@ -1,7 +1,7 @@ --- layout: default title: Protocol -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 2 --- diff --git a/_search-plugins/sql/settings.md b/_search-plugins/sql/settings.md index 3c142213749..dd07747555c 100644 --- a/_search-plugins/sql/settings.md +++ b/_search-plugins/sql/settings.md @@ -1,7 +1,7 @@ --- layout: default title: Settings -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 77 --- diff --git a/_search-plugins/sql/sql/aggregations.md b/_search-plugins/sql/sql/aggregations.md index 1b7e0108efd..80ee15a8466 100644 --- a/_search-plugins/sql/sql/aggregations.md +++ b/_search-plugins/sql/sql/aggregations.md @@ -2,7 +2,7 @@ layout: default title: Aggregation Functions parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 11 --- diff --git a/_search-plugins/sql/sql/basic.md b/_search-plugins/sql/sql/basic.md index aabe809b7e1..43bfc1627af 100644 --- a/_search-plugins/sql/sql/basic.md +++ b/_search-plugins/sql/sql/basic.md @@ -2,7 +2,7 @@ layout: default title: Basic Queries parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 5 --- diff --git a/_search-plugins/sql/sql/complex.md b/_search-plugins/sql/sql/complex.md index 7e15c33500d..656481573c3 100644 --- a/_search-plugins/sql/sql/complex.md +++ b/_search-plugins/sql/sql/complex.md @@ -2,7 +2,7 @@ layout: default title: Complex Queries parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 6 --- diff --git a/_search-plugins/sql/sql/delete.md b/_search-plugins/sql/sql/delete.md index fec97bb4929..30af7b78d5f 100644 --- a/_search-plugins/sql/sql/delete.md +++ b/_search-plugins/sql/sql/delete.md @@ -2,7 +2,7 @@ layout: default title: Delete parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 12 --- diff --git a/_search-plugins/sql/sql/functions.md b/_search-plugins/sql/sql/functions.md index 446abac0665..4dcff831507 100755 --- a/_search-plugins/sql/sql/functions.md +++ b/_search-plugins/sql/sql/functions.md @@ -2,13 +2,13 @@ layout: default title: Functions parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 7 --- # Functions -`SQL` language supports all SQL plugin [functions]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/), including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few function synonyms which are available in `SQL` only. +`SQL` language supports all SQL plugin [common functions]({{site.url}}{{site.baseurl}}/search-plugins/sql/functions/), including [relevance search]({{site.url}}{{site.baseurl}}/search-plugins/sql/full-text/), but also introduces few function synonyms which are available in `SQL` only. These synonyms are provided by `V1` engine, please see [limitations page]({{site.url}}{{site.baseurl}}/search-plugins/sql/limitation) for more info about it. ## Match query diff --git a/_search-plugins/sql/sql/index.md b/_search-plugins/sql/sql/index.md index eee4336a070..d01655bffbf 100644 --- a/_search-plugins/sql/sql/index.md +++ b/_search-plugins/sql/sql/index.md @@ -1,7 +1,7 @@ --- layout: default title: SQL -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 4 has_children: true redirect_from: diff --git a/_search-plugins/sql/sql/jdbc.md b/_search-plugins/sql/sql/jdbc.md index 80c3ab81289..9c7b79acd48 100644 --- a/_search-plugins/sql/sql/jdbc.md +++ b/_search-plugins/sql/sql/jdbc.md @@ -2,7 +2,7 @@ layout: default title: JDBC Driver parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 71 --- diff --git a/_search-plugins/sql/sql/metadata.md b/_search-plugins/sql/sql/metadata.md index 3e939491f95..f4fa80c3b98 100644 --- a/_search-plugins/sql/sql/metadata.md +++ b/_search-plugins/sql/sql/metadata.md @@ -2,7 +2,7 @@ layout: default title: Metadata Queries parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 9 --- diff --git a/_search-plugins/sql/sql/odbc.md b/_search-plugins/sql/sql/odbc.md index 5ad51624426..eb4ff317bf8 100644 --- a/_search-plugins/sql/sql/odbc.md +++ b/_search-plugins/sql/sql/odbc.md @@ -2,7 +2,7 @@ layout: default title: ODBC Driver parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 72 --- diff --git a/_search-plugins/sql/sql/partiql.md b/_search-plugins/sql/sql/partiql.md index fe7b0d54643..6fecf297458 100644 --- a/_search-plugins/sql/sql/partiql.md +++ b/_search-plugins/sql/sql/partiql.md @@ -2,7 +2,7 @@ layout: default title: JSON Support parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 8 --- diff --git a/_search-plugins/sql/troubleshoot.md b/_search-plugins/sql/troubleshoot.md index a66009ccf8a..c67c93a62d9 100644 --- a/_search-plugins/sql/troubleshoot.md +++ b/_search-plugins/sql/troubleshoot.md @@ -1,7 +1,7 @@ --- layout: default title: Troubleshooting -parent: SQL Plugin - SQL & PPL +parent: SQL & PPL nav_order: 88 --- diff --git a/_search-plugins/sql/workbench.md b/_search-plugins/sql/workbench.md index 8c09a177da3..a1703a71271 100644 --- a/_search-plugins/sql/workbench.md +++ b/_search-plugins/sql/workbench.md @@ -2,7 +2,7 @@ layout: default title: Query Workbench parent: SQL -grand_parent: SQL Plugin - SQL & PPL +grand_parent: SQL & PPL nav_order: 1 ---