diff --git a/docs/src/main/sphinx/client/jdbc.md b/docs/src/main/sphinx/client/jdbc.md index cf974490f9cb..8b2f8a8e04d8 100644 --- a/docs/src/main/sphinx/client/jdbc.md +++ b/docs/src/main/sphinx/client/jdbc.md @@ -23,14 +23,12 @@ Download {maven_download}`jdbc` and add it to the classpath of your Java applica The driver is also available from Maven Central: -```{eval-rst} -.. parsed-literal:: - - - io.trino - trino-jdbc - \ |version|\ - +```xml + + io.trino + trino-jdbc + |trino_version| + ``` We recommend using the latest version of the JDBC driver. A list of all diff --git a/docs/src/main/sphinx/conf.py b/docs/src/main/sphinx/conf.py index baa17cfe1cfc..4f15464425bb 100644 --- a/docs/src/main/sphinx/conf.py +++ b/docs/src/main/sphinx/conf.py @@ -102,10 +102,6 @@ def setup(app): default_role = 'backquote' -rst_epilog = """ -.. |trino_server_release| replace:: ``trino-server-{release}`` -""".replace('{release}', release) - # Any replace that is inside of a code block should be added here # https://stackoverflow.com/questions/8821511/substitutions-inside-sphinx-code-blocks-arent-replaced diff --git a/docs/src/main/sphinx/connector/jdbc-common-configurations.fragment b/docs/src/main/sphinx/connector/jdbc-common-configurations.fragment index 9846f44595e0..dc30d1a1a671 100644 --- a/docs/src/main/sphinx/connector/jdbc-common-configurations.fragment +++ b/docs/src/main/sphinx/connector/jdbc-common-configurations.fragment @@ -3,52 +3,51 @@ The following table describes general catalog configuration properties for the connector: -```{eval-rst} -.. list-table:: - :widths: 30, 40, 30 - :header-rows: 1 +:::{list-table} +:widths: 30, 40, 30 +:header-rows: 1 - * - Property name - - Description - - Default value - * - ``case-insensitive-name-matching`` - - Support case insensitive schema and table names. - - ``false`` - * - ``case-insensitive-name-matching.cache-ttl`` - - This value should be a :ref:`prop-type-duration`. - - ``1m`` - * - ``case-insensitive-name-matching.config-file`` - - Path to a name mapping configuration file in JSON format that allows - Trino to disambiguate between schemas and tables with similar names in - different cases. - - ``null`` - * - ``case-insensitive-name-matching.config-file.refresh-period`` - - Frequency with which Trino checks the name matching configuration file - for changes. This value should be a :ref:`prop-type-duration`. - - (refresh disabled) - * - ``metadata.cache-ttl`` - - :ref:`The duration ` for which metadata, including +* - Property name + - Description + - Default value +* - `case-insensitive-name-matching` + - Support case insensitive schema and table names. + - `false` +* - `case-insensitive-name-matching.cache-ttl` + - This value should be a [](prop-type-duration). + - `1m` +* - `case-insensitive-name-matching.config-file` + - Path to a name mapping configuration file in JSON format that allows + Trino to disambiguate between schemas and tables with similar names in + different cases. + - `null` +* - `case-insensitive-name-matching.config-file.refresh-period` + - Frequency with which Trino checks the name matching configuration file + for changes. This value should be a [](prop-type-duration). + - (refresh disabled) +* - `metadata.cache-ttl` + - [The duration](prop-type-duration) for which metadata, including table and column statistics, is cached. - - ``0s`` (caching disabled) - * - ``metadata.cache-missing`` - - Cache the fact that metadata, including table and column statistics, is - not available - - ``false`` - * - ``metadata.cache-maximum-size`` - - Maximum number of objects stored in the metadata cache - - ``10000`` - * - ``write.batch-size`` - - Maximum number of statements in a batched execution. - Do not change this setting from the default. Non-default values may - negatively impact performance. - - ``1000`` - * - ``dynamic-filtering.enabled`` - - Push down dynamic filters into JDBC queries - - ``true`` - * - ``dynamic-filtering.wait-timeout`` - - Maximum :ref:`prop-type-duration` for which Trino will wait for dynamic - filters to be collected from the build side of joins before starting a - JDBC query. Using a large timeout can potentially result in more detailed - dynamic filters. However, it can also increase latency for some queries. - - ``20s`` -``` + - `0s` (caching disabled) +* - `metadata.cache-missing` + - Cache the fact that metadata, including table and column statistics, is + not available + - `false` +* - `metadata.cache-maximum-size` + - Maximum number of objects stored in the metadata cache + - `10000` +* - `write.batch-size` + - Maximum number of statements in a batched execution. Do not change + this setting from the default. Non-default values may negatively + impact performance. + - `1000` +* - `dynamic-filtering.enabled` + - Push down dynamic filters into JDBC queries + - `true` +* - `dynamic-filtering.wait-timeout` + - Maximum [](prop-type-duration) for which Trino waits for dynamic + filters to be collected from the build side of joins before starting a + JDBC query. Using a large timeout can potentially result in more detailed + dynamic filters. However, it can also increase latency for some queries. + - `20s` +::: diff --git a/docs/src/main/sphinx/connector/join-pushdown-enabled-true.fragment b/docs/src/main/sphinx/connector/join-pushdown-enabled-true.fragment index abc68ba054b1..738785f2d28e 100644 --- a/docs/src/main/sphinx/connector/join-pushdown-enabled-true.fragment +++ b/docs/src/main/sphinx/connector/join-pushdown-enabled-true.fragment @@ -12,25 +12,24 @@ performance. The following table describes catalog configuration properties for join pushdown: -```{eval-rst} -.. list-table:: - :widths: 30, 40, 30 - :header-rows: 1 +:::{list-table} +:widths: 30, 40, 30 +:header-rows: 1 - * - Property name - - Description - - Default value - * - ``join-pushdown.enabled`` - - Enable :ref:`join pushdown `. Equivalent :ref:`catalog - session property ` is - ``join_pushdown_enabled``. - - ``true`` - * - ``join-pushdown.strategy`` - - Strategy used to evaluate whether join operations are pushed down. Set to - ``AUTOMATIC`` to enable cost-based join pushdown, or ``EAGER`` to - push down joins whenever possible. Note that ``EAGER`` can push down joins - even when table statistics are unavailable, which may result in degraded - query performance. Because of this, ``EAGER`` is only recommended for - testing and troubleshooting purposes. - - ``AUTOMATIC`` -``` +* - Property name + - Description + - Default value +* - `join-pushdown.enabled` + - Enable [join pushdown](join-pushdown). Equivalent [catalog + session property](session-properties-definition) is + `join_pushdown_enabled`. + - `true` +* - `join-pushdown.strategy` + - Strategy used to evaluate whether join operations are pushed down. Set to + `AUTOMATIC` to enable cost-based join pushdown, or `EAGER` to + push down joins whenever possible. Note that `EAGER` can push down joins + even when table statistics are unavailable, which may result in degraded + query performance. Because of this, `EAGER` is only recommended for + testing and troubleshooting purposes. + - `AUTOMATIC` +::: diff --git a/docs/src/main/sphinx/connector/json-decoder.fragment b/docs/src/main/sphinx/connector/json-decoder.fragment index 197be96f200d..b6ce45611452 100644 --- a/docs/src/main/sphinx/connector/json-decoder.fragment +++ b/docs/src/main/sphinx/connector/json-decoder.fragment @@ -19,30 +19,29 @@ types. The following table lists Trino data types, which can be used in `type` and matching field decoders, and specified via `dataFormat` attribute: -```{eval-rst} -.. list-table:: - :widths: 40, 60 - :header-rows: 1 +:::{list-table} +:widths: 40, 60 +:header-rows: 1 - * - Trino data type - - Allowed ``dataFormat`` values - * - ``BIGINT``, ``INTEGER``, ``SMALLINT``, ``TINYINT``, ``DOUBLE``, - ``BOOLEAN``, ``VARCHAR``, ``VARCHAR(x)`` - - Default field decoder (omitted ``dataFormat`` attribute) - * - ``DATE`` - - ``custom-date-time``, ``iso8601`` - * - ``TIME`` - - ``custom-date-time``, ``iso8601``, ``milliseconds-since-epoch``, - ``seconds-since-epoch`` - * - ``TIME WITH TIME ZONE`` - - ``custom-date-time``, ``iso8601`` - * - ``TIMESTAMP`` - - ``custom-date-time``, ``iso8601``, ``rfc2822``, - ``milliseconds-since-epoch``, ``seconds-since-epoch`` - * - ``TIMESTAMP WITH TIME ZONE`` - - ``custom-date-time``, ``iso8601``, ``rfc2822``, - ``milliseconds-since-epoch``, ``seconds-since-epoch`` -``` +* - Trino data type + - Allowed `dataFormat` values +* - `BIGINT`, `INTEGER`, `SMALLINT`, `TINYINT`, `DOUBLE`, `BOOLEAN`, + `VARCHAR`, `VARCHAR(x)` + - Default field decoder (omitted `dataFormat` attribute) +* - `DATE` + - `custom-date-time`, `iso8601` +* - `TIME` + - `custom-date-time`, `iso8601`, `milliseconds-since-epoch`, + `seconds-since-epoch` +* - `TIME WITH TIME ZONE` + - `custom-date-time`, `iso8601` +* - `TIMESTAMP` + - `custom-date-time`, `iso8601`, `rfc2822`, `milliseconds-since-epoch`, + `seconds-since-epoch` +* - `TIMESTAMP WITH TIME ZONE` + - `custom-date-time`, `iso8601`, `rfc2822`, + `milliseconds-since-epoch`, `seconds-since-epoch` +::: No other types are supported. diff --git a/docs/src/main/sphinx/connector/mongodb.md b/docs/src/main/sphinx/connector/mongodb.md index 77269717f780..ff66ceaef678 100644 --- a/docs/src/main/sphinx/connector/mongodb.md +++ b/docs/src/main/sphinx/connector/mongodb.md @@ -315,23 +315,23 @@ SELECT CAST(_id AS VARCHAR), * FROM orders WHERE _id = ObjectId('55b151633864d64 The first four bytes of each [ObjectId](https://docs.mongodb.com/manual/reference/method/ObjectId) represent an embedded timestamp of its creation time. Trino provides a couple of functions to take advantage of this MongoDB feature. -```{eval-rst} -.. function:: objectid_timestamp(ObjectId) -> timestamp +:::{function} objectid_timestamp(ObjectId) -> timestamp +Extracts the TIMESTAMP WITH TIME ZONE from a given ObjectId: - Extracts the TIMESTAMP WITH TIME ZONE from a given ObjectId:: - - SELECT objectid_timestamp(ObjectId('507f191e810c19729de860ea')); - -- 2012-10-17 20:46:22.000 UTC +```sql +SELECT objectid_timestamp(ObjectId('507f191e810c19729de860ea')); +-- 2012-10-17 20:46:22.000 UTC ``` +::: -```{eval-rst} -.. function:: timestamp_objectid(timestamp) -> ObjectId - - Creates an ObjectId from a TIMESTAMP WITH TIME ZONE:: +:::{function} timestamp_objectid(timestamp) -> ObjectId +Creates an ObjectId from a TIMESTAMP WITH TIME ZONE: - SELECT timestamp_objectid(TIMESTAMP '2021-08-07 17:51:36 +00:00'); - -- 61 0e c8 28 00 00 00 00 00 00 00 00 +```sql +SELECT timestamp_objectid(TIMESTAMP '2021-08-07 17:51:36 +00:00'); +-- 61 0e c8 28 00 00 00 00 00 00 00 00 ``` +::: In MongoDB, you can filter all the documents created after `2021-08-07 17:51:36` with a query like this: diff --git a/docs/src/main/sphinx/connector/raw-decoder.fragment b/docs/src/main/sphinx/connector/raw-decoder.fragment index 68d2de457445..12a6718ef5f5 100644 --- a/docs/src/main/sphinx/connector/raw-decoder.fragment +++ b/docs/src/main/sphinx/connector/raw-decoder.fragment @@ -28,26 +28,25 @@ The `type` attribute defines the Trino data type on which the value is mapped. Depending on the Trino type assigned to a column, different values of dataFormat can be used: -```{eval-rst} -.. list-table:: - :widths: 40, 60 - :header-rows: 1 - - * - Trino data type - - Allowed ``dataFormat`` values - * - ``BIGINT`` - - ``BYTE``, ``SHORT``, ``INT``, ``LONG`` - * - ``INTEGER`` - - ``BYTE``, ``SHORT``, ``INT`` - * - ``SMALLINT`` - - ``BYTE``, ``SHORT`` - * - ``DOUBLE`` - - ``DOUBLE``, ``FLOAT`` - * - ``BOOLEAN`` - - ``BYTE``, ``SHORT``, ``INT``, ``LONG`` - * - ``VARCHAR`` / ``VARCHAR(x)`` - - ``BYTE`` -``` +:::{list-table} +:widths: 40, 60 +:header-rows: 1 + +* - Trino data type + - Allowed `dataFormat` values +* - `BIGINT` + - `BYTE`, `SHORT`, `INT`, `LONG` +* - `INTEGER` + - `BYTE`, `SHORT`, `INT` +* - `SMALLINT` + - `BYTE`, `SHORT` +* - `DOUBLE` + - `DOUBLE`, `FLOAT` +* - `BOOLEAN` + - `BYTE`, `SHORT`, `INT`, `LONG` +* - `VARCHAR` / `VARCHAR(x)` + - `BYTE` +::: No other types are supported. diff --git a/docs/src/main/sphinx/connector/system.md b/docs/src/main/sphinx/connector/system.md index 07ad18fc87d1..a3de46eb182d 100644 --- a/docs/src/main/sphinx/connector/system.md +++ b/docs/src/main/sphinx/connector/system.md @@ -137,12 +137,12 @@ idle time, initialization parameters, and accessed catalogs. ## System connector procedures -```{eval-rst} -.. function:: runtime.kill_query(query_id, message) +:::{function} runtime.kill_query(query_id, message) - Kill the query identified by ``query_id``. The query failure message - includes the specified ``message``. ``message`` is optional. -``` +Kill the query identified by `query_id`. The query failure message includes the +specified `message`. `message` is optional. + +::: (system-type-mapping)= diff --git a/docs/src/main/sphinx/sql/reset-session-authorization.md b/docs/src/main/sphinx/sql/reset-session-authorization.md new file mode 100644 index 000000000000..6665f9f56ba1 --- /dev/null +++ b/docs/src/main/sphinx/sql/reset-session-authorization.md @@ -0,0 +1,17 @@ +# RESET SESSION AUTHORIZATION + +## Synopsis + +```text +RESET SESSION AUTHORIZATION +``` + +## Description + +Resets the current authorization user back to the original user. The original +user is usually the authenticated user (principal), or it can be the session +user when the session user is provided by the client. + +## See also + +[](set-session-authorization) diff --git a/docs/src/main/sphinx/sql/reset-session-authorization.rst b/docs/src/main/sphinx/sql/reset-session-authorization.rst deleted file mode 100644 index b1b163a5c90a..000000000000 --- a/docs/src/main/sphinx/sql/reset-session-authorization.rst +++ /dev/null @@ -1,22 +0,0 @@ -=========================== -RESET SESSION AUTHORIZATION -=========================== - -Synopsis --------- - -.. code-block:: none - - RESET SESSION AUTHORIZATION - -Description ------------ - -Resets the current authorization user back to the original user. -The original user is usually the authenticated user (principal), -or it can be the session user when the session user is provided by the client. - -See Also --------- - -:doc:`set-session-authorization` diff --git a/docs/src/main/sphinx/sql/set-session-authorization.md b/docs/src/main/sphinx/sql/set-session-authorization.md new file mode 100644 index 000000000000..719bc2506a5f --- /dev/null +++ b/docs/src/main/sphinx/sql/set-session-authorization.md @@ -0,0 +1,49 @@ +# SET SESSION AUTHORIZATION + +## Synopsis + +```text +SET SESSION AUTHORIZATION username +``` + +## Description + +Changes the current user of the session. For the `SET SESSION AUTHORIZATION +username` statement to succeed, the original user (that the client connected +with) must be able to impersonate the specified user. User impersonation can be +enabled in the system access control. + +## Examples + +In the following example, the original user when the connection to Trino is made +is Kevin. The following sets the session authorization user to John: + +```sql +SET SESSION AUTHORIZATION 'John'; +``` + +Queries will now execute as John instead of Kevin. + +All supported syntax to change the session authorization users are shown below. + +Changing the session authorization with single quotes: + +```sql +SET SESSION AUTHORIZATION 'John'; +``` + +Changing the session authorization with double quotes: + +```sql +SET SESSION AUTHORIZATION "John"; +``` + +Changing the session authorization without quotes: + +```sql +SET SESSION AUTHORIZATION John; +``` + +## See also + +[](reset-session-authorization) diff --git a/docs/src/main/sphinx/sql/set-session-authorization.rst b/docs/src/main/sphinx/sql/set-session-authorization.rst deleted file mode 100644 index 98634dd11235..000000000000 --- a/docs/src/main/sphinx/sql/set-session-authorization.rst +++ /dev/null @@ -1,47 +0,0 @@ -========================= -SET SESSION AUTHORIZATION -========================= - -Synopsis --------- - -.. code-block:: none - - SET SESSION AUTHORIZATION username - -Description ------------ - -Changes the current user of the session. -For the ``SET SESSION AUTHORIZATION username`` statement to succeed, -the the original user (that the client connected with) must be able to impersonate the specified user. -User impersonation can be enabled in the system access control. - -Examples --------- - -In the following example, the original user when the connection to Trino is made is Kevin. -The following sets the session authorization user to John:: - - SET SESSION AUTHORIZATION 'John'; - -Queries will now execute as John instead of Kevin. - -All supported syntax to change the session authorization users are shown below. - -Changing the session authorization with single quotes:: - - SET SESSION AUTHORIZATION 'John'; - -Changing the session authorization with double quotes:: - - SET SESSION AUTHORIZATION "John"; - -Changing the session authorization without quotes:: - - SET SESSION AUTHORIZATION John; - -See Also --------- - -:doc:`reset-session-authorization`