elastic · florent-leborgne · Feb 5, 2025 · Feb 4, 2025 · Feb 4, 2025 · Feb 4, 2025
@@ -1,8 +1,3 @@
----
-mapped_pages:
-  - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-analyze.html
----
-
 # Query languages [search-analyze-query-languages]
 
 {{es}} provides a number of query languages for interacting with your data.

@@ -1,6 +1,8 @@
 ---
+navigation_title: Conventions
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-concepts.html
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/_mapping_concepts_across_sql_and_elasticsearch.html
 ---
 
 # Conventions and Terminology [sql-concepts]
@@ -14,4 +16,23 @@ This documentation while trying to be complete, does assume the reader has *basi
 
 As a general rule, Elasticsearch SQL as the name indicates provides a SQL interface to {{es}}. As such, it follows the SQL terminology and conventions first, whenever possible. However the backing engine itself is {{es}} for which Elasticsearch SQL was purposely created hence why features or concepts that are not available, or cannot be mapped correctly, in SQL appear in Elasticsearch SQL. Last but not least, Elasticsearch SQL tries to obey the [principle of least surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), though as all things in the world, everything is relative.
 
+## Mapping concepts across SQL and Elasticsearch [_mapping_concepts_across_sql_and_es]
+
+While SQL and {{es}} have different terms for the way the data is organized (and different semantics), essentially their purpose is the same.
+
+So let’s start from the bottom; these roughly are:
+
+| SQL | {{es}} | Description |
+| --- | --- | --- |
+| `column` | `field` | In both cases, at the lowest level, data is stored in *named* entries, of a variety of [data types](sql-data-types.md), containing *one* value. SQL calls such an entry a *column* while {{es}} a *field*.Notice that in {{es}} a field can contain *multiple* values of the same type (essentially a list) while in SQL, a *column* can contain *exactly* one value of said type.Elasticsearch SQL will do its best to preserve the SQL semantic and, depending on the query, reject those that return fields with more than one value. |
+| `row` | `document` | `Column`s and `field`s do *not* exist by themselves; they are part of a `row` or a `document`. The two have slightly different semantics: a `row` tends to be *strict* (and have more enforcements) while a `document` tends to be a bit more flexible or loose (while still having a structure). |
+| `table` | `index` | The target against which queries, whether in SQL or {{es}} get executed against. |
+| `schema` | *implicit* | In RDBMS, `schema` is mainly a namespace of tables and typically used as a security boundary. {{es}} does not provide an equivalent concept for it. However when security is enabled, {{es}} automatically applies the security enforcement so that a role sees only the data it is allowed to (in SQL jargon, its *schema*). |
+| `catalog` or `database` | `cluster` instance | In SQL, `catalog` or `database` are used interchangeably and represent a set of schemas that is, a number of tables.In {{es}} the set of indices available are grouped in a `cluster`. The semantics also differ a bit; a `database` is essentially yet another namespace (which can have some implications on the way data is stored) while an {{es}} `cluster` is a runtime instance, or rather a set of at least one {{es}} instance (typically running distributed).In practice this means that while in SQL one can potentially have multiple catalogs inside an instance, in {{es}} one is restricted to only *one*. |
+| `cluster` | `cluster` (federated) | Traditionally in SQL, *cluster* refers to a single RDBMS instance which contains a number of `catalog`s or `database`s (see above). The same word can be reused inside {{es}} as well however its semantic clarified a bit.<br>While RDBMS tend to have only one running instance, on a single machine (*not* distributed), {{es}} goes the opposite way and by default, is distributed and multi-instance.<br>Further more, an {{es}} `cluster` can be connected to other `cluster`s in a *federated* fashion thus `cluster` means:<br>single cluster::Multiple {{es}} instances typically distributed across machines, running within the same namespace.multiple clusters::Multiple clusters, each with its own namespace, connected to each other in a federated setup (see [{{ccs-cap}}](../../../solutions/search/cross-cluster-search.md)). |
+
+As one can see while the mapping between the concepts are not exactly one to one and the semantics somewhat different, there are more things in common than differences. In fact, thanks to SQL declarative nature, many concepts can move across {{es}} transparently and the terminology of the two likely to be used interchangeably throughout the rest of the material.
+
+
+
 
@@ -1038,7 +1038,7 @@ TO_CHAR(
 
 **Output**: string
 
-**Description**: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting pattern conforms to [PostgreSQL Template Patterns for Date/Time Formatting](https://www.postgresql.org/docs/13/functions-formatting.md).
+**Description**: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting pattern conforms to [PostgreSQL Template Patterns for Date/Time Formatting](https://www.postgresql.org/docs/13/functions-formatting.html).
 
 ::::{note} 
 If the 1st argument is of type `time`, then the pattern specified by the 2nd argument cannot contain date related units (e.g. *dd*, *MM*, *YYYY*, etc.). If it contains such units an error is returned.<br> The result of the patterns `TZ` and `tz` (time zone abbreviations) in some cases differ from the results returned by the `TO_CHAR` in PostgreSQL. The reason is that the time zone abbreviations specified by the JDK are different from the ones specified by PostgreSQL. This function might show an actual time zone abbreviation instead of the generic `LMT` or empty string or offset returned by the PostgreSQL implementation. The summer/daylight markers might also differ between the two implementations (e.g. will show `HT` instead of `HST` for Hawaii).<br> The `FX`, `TM`, `SP` pattern modifiers are not supported and will show up as `FX`, `TM`, `SP` literals in the output.

@@ -1,4 +1,5 @@
 ---
+navigation_title: Getting started
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-getting-started.html
 ---

@@ -1,10 +1,11 @@
 ---
+navigation_title: Console
 mapped_urls:
   - https://www.elastic.co/guide/en/kibana/current/console-kibana.html
   - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-api-console.html
 ---
 
-# Console
+# Run API requests with Console [console-kibana]
 
 % What needs to be done: Refine
 
@@ -19,4 +20,228 @@ mapped_urls:
 
 $$$configuring-console$$$
 
-$$$import-export-console-requests$$$
+$$$import-export-console-requests$$$
+
+
+**Console** is an interactive UI for sending requests to [{{es}} APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html) and [{{kib}} APIs](https://www.elastic.co/docs/api) and viewing their responses.
+
+:::{image} ../../../images/kibana-console.png
+:alt: Console
+:class: screenshot
+:::
+
+To go to **Console**, find **Dev Tools** in the navigation menu or use the [global search bar](../../../get-started/the-stack.md#kibana-navigation-search).
+
+You can also find Console directly on certain Search solution and Elasticsearch serverless project pages, where you can expand it from the footer. This Console, called **Persistent Console**, has the same capabilities and shares the same history as the Console in **Dev Tools**.
+
+:::{image} ../../../images/kibana-persistent-console.png
+:alt: Console
+:class: screenshot
+:::
+
+
+## Write requests [console-api]
+
+**Console** accepts commands in a simplified HTTP request syntax. For example, the following `GET` request calls the {es} `_search` API:
+
+```js
+GET /_search
+{
+  "query": {
+    "match_all": {}
+  }
+}
+```
+
+Here is the equivalent command in cURL:
+
+```bash
+curl -XGET "http://localhost:9200/_search" -d'
+{
+  "query": {
+    "match_all": {}
+  }
+}'
+```
+
+Prepend requests to a {{kib}} API endpoint with `kbn:`
+
+```bash
+GET kbn:/api/index_management/indices
+```
+
+
+### Autocomplete [console-autocomplete]
+
+When you’re typing a command, **Console** makes context-sensitive suggestions. These suggestions show you the parameters for each API and speed up your typing.
+
+You can configure your preferences for autocomplete in the [Console settings](../../../explore-analyze/query-filter/tools/console.md#configuring-console).
+
+
+### Comments [console-comments]
+
+You can write comments or temporarily disable parts of a request by using double forward slashes or pound signs to create single-line comments.
+
+```js
+# This request searches all of your indices.
+GET /_search
+{
+  // The query parameter indicates query context.
+  "query": {
+    "match_all": {} // Matches all documents.
+  }
+}
+```
+
+You can also use a forward slash followed by an asterisk to mark the beginning of multi-line comments. An asterisk followed by a forward slash marks the end.
+
+```js
+GET /_search
+{
+  "query": {
+    /*"match_all": {
+      "boost": 1.2
+    }*/
+    "match_none": {}
+  }
+}
+```
+
+
+### Variables [console-variables]
+
+Click **Variables** to create, edit, and delete variables.
+
+:::{image} ../../../images/kibana-variables.png
+:alt: Variables
+:class: screenshot
+:::
+
+You can refer to these variables in the paths and bodies of your requests. Each variable can be referenced multiple times.
+
+```js
+GET ${pathVariable}
+{
+  "query": {
+    "match": {
+      "${bodyNameVariable}": "${bodyValueVariable}"
+    }
+  }
+}
+```
+
+By default, variables in the body may be substituted as a boolean, number, array, or object by removing nearby quotes instead of a string with surrounding quotes. Triple quotes overwrite this default behavior and enforce simple replacement as a string.
+
+```js
+GET /locations/_search
+{
+  "query": {
+    "bool": {
+      "must": {
+        "match": {
+          // ${shopName} shall be replaced as a string if the variable exists.
+          "shop.name": """${shopName}"""
+        }
+      },
+      "filter": {
+        "geo_distance": {
+          "distance": "12km",
+          // "${pinLocation}" may be substituted with an array such as [-70, 40].
+          "pin.location": "${pinLocation}"
+        }
+      }
+    }
+  }
+}
+```
+
+
+### Auto-formatting [auto-formatting]
+
+The auto-formatting capability can help you format requests to be more readable. Select one or more requests that you want to format, open the contextual menu, and then select **Auto indent**.
+
+
+### Keyboard shortcuts [keyboard-shortcuts]
+
+Go to line number
+:   `Ctrl/Cmd` + `L`
+
+Auto-indent current request
+:   `Ctrl/Cmd` + `I`
+
+Jump to next request end
+:   `Ctrl/Cmd` + `↓`
+
+Jump to previous request end
+:   `Ctrl/Cmd` + `↑`
+
+Open documentation for current request
+:   `Ctrl/Cmd` + `/`
+
+Run current request
+:   `Ctrl/Cmd` + `Enter`
+
+Apply current or topmost term in autocomplete menu
+:   `Enter` or `Tab`
+
+Close autocomplete menu
+:   `Esc`
+
+Navigate items in autocomplete menu
+:   `↓` + `↑`
+
+
+### View API docs [console-view-api]
+
+To view the documentation for an API endpoint, select the request, then open the contextual menu and select **Open API reference**.
+
+
+## Run requests [console-request]
+
+When you’re ready to run a request, select the request, and click the play button.
+
+The result of the request execution is displayed in the response panel, where you can see:
+
+* the JSON response
+* the HTTP status code corresponding to the request
+* The execution time, in ms.
+
+::::{tip}
+You can select multiple requests and submit them together. **Console** executes the requests one by one. Submitting multiple requests is helpful when you’re debugging an issue or trying query combinations in multiple scenarios.
+::::
+
+
+
+## Import and export requests [import-export-console-requests]
+
+You can export requests:
+
+* **to a TXT file**, by using the **Export requests** button. When using this method, all content of the input panel is copied, including comments, requests, and payloads. All of the formatting is preserved and allows you to re-import the file later, or to a different environment, using the **Import requests** button.
+
+    ::::{tip}
+    When importing a TXT file containing Console requests, the current content of the input panel is replaced. Export it first if you don’t want to lose it, or find it in the **History** tab if you already ran the requests.
+    ::::
+
+* by copying them individually as **curl**, **JavaScript**, or **Python**. To do this, select a request, then open the contextual menu and select **Copy as**. When using this action, requests are copied individually to your clipboard. You can save your favorite language to make the copy action faster the next time you use it.
+
+    When running copied requests from an external environment, you’ll need to add [authentication information](https://www.elastic.co/docs/api/doc/kibana/authentication) to the request.
+
+
+
+## Get your request history [console-history]
+
+**Console** maintains a list of the last 500 requests that you tried to execute. To view them, open the **History** tab.
+
+You can run a request from your history again by selecting the request and clicking **Add and run**. If you want to add it back to the Console input panel without running it yet, click **Add** instead. It is added to the editor at the current cursor position.
+
+
+## Configure Console settings [configuring-console]
+
+Go to the **Config** tab of **Console** to customize its display, autocomplete, and accessibility settings.
+
+
+## Disable Console [disable-console]
+
+If you don’t want to use **Console**, you can disable it by setting `console.ui.enabled` to `false` in your `kibana.yml` configuration file. Changing this setting causes the server to regenerate assets on the next startup, which might cause a delay before pages start being served.
+
+You can also choose to only disable the persistent console that shows in the footer of several Kibana pages. To do that, go to **Stack Management** > **Advanced Settings**, and turn off the `devTools:enablePersistentConsole` setting.