OpenSearch/docs/en/sql/endpoints/translate.asciidoc

[role="xpack"]
[[sql-translate]]
== SQL Translate API

The SQL Translate API accepts SQL in a JSON document and translates it
into native Elasticsearch queries. For example:

[source,js]
--------------------------------------------------
POST /_xpack/sql/translate
{
    "query": "SELECT * FROM library ORDER BY page_count DESC",
    "fetch_size": 10
}
--------------------------------------------------
// CONSOLE
// TEST[setup:library]

Which returns:

[source,js]
--------------------------------------------------
{
    "size" : 10,
    "docvalue_fields" : [
        "page_count",
        "release_date"
    ],
    "_source": {
        "includes": [
            "author",
            "name"
        ],
        "excludes": []
    },
    "sort" : [
        {
            "page_count" : {
                "order" : "desc"
            }
        }
    ]
}
--------------------------------------------------
// TESTRESPONSE

Which is the request that SQL will run to provide the results.
In this case, SQL will use the <<search-request-scroll,scroll>>
API. If the result contained an aggregation then SQL would use
the normal <<search-request-body,search>> API.

The request body accepts all of the <<sql-rest-fields,fields>> that
the <<sql-rest,SQL REST API>> accepts except `cursor`.

[[sql-translate-permissions]]
[NOTE]
===============================
If you are using Security you need to add a few permissions to
users so they can run translate SQL. To translate SQL a user
needs `read` and `indices:admin/get`. The following example
configures a role that can run SQL against the `test` and
`bort` indices:

["source","yaml",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-tests}/security/roles.yml[rest]
--------------------------------------------------
===============================