Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs to reflect recent changes. #285

Merged
merged 5 commits into from
Jul 10, 2023
Merged

Update docs to reflect recent changes. #285

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7498ba4
Update docs.
Yury-Fridlyand Jul 8, 2023
0e4dacd
Apply suggestions from code review
Yury-Fridlyand Jul 10, 2023
9752afb
Add example of quote escaping.
Yury-Fridlyand Jul 10, 2023
c7b0e99
Update docs/user/general/datatypes.rst
Yury-Fridlyand Jul 10, 2023
7c3018b
Update docs/user/general/datatypes.rst
Yury-Fridlyand Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/user/dql/expressions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ Here is an example for different type of comparison operators::
+---------+----------+---------+----------+----------+---------+

It is possible to compare datetimes. When comparing different datetime types, for example `DATE` and `TIME`, both converted to `DATETIME`.
The following rule is applied on coversion: a `TIME` applied to today's date; `DATE` is interpreted at midnight.
The following rule is applied on coversion: a `TIME` applied to today's date; `DATE` is interpreted at midnight. See example below::

os> SELECT current_time() > current_date() AS `now.time > today`, typeof(current_time()) AS `now.time.type`, typeof(current_date()) AS `now.date.type`;
fetched rows / total rows = 1/1
Expand Down
107 changes: 91 additions & 16 deletions docs/user/general/datatypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,15 +155,15 @@ The following matrix illustrates the conversions allowed by our query engine for
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| STRING | E | E | E | E | E | E | IE | X | X | N/A | IE | IE | IE | IE | X | X | X | X | X | X |
matthewryanwells marked this conversation as resolved.
Show resolved Hide resolved
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| TIMESTAMP | X | X | X | X | X | X | X | X | X | E | N/A | | | X | X | X | X | X | X | X |
| TIMESTAMP | X | X | X | X | X | X | X | X | X | E | N/A | IE | IE | IE | X | X | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| DATE | X | X | X | X | X | X | X | X | X | E | | N/A | | X | X | X | X | X | X | X |
| DATE | X | X | X | X | X | X | X | X | X | E | E | N/A | IE | E | X | X | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| TIME | X | X | X | X | X | X | X | X | X | E | | | N/A | X | X | X | X | X | X | X |
| TIME | X | X | X | X | X | X | X | X | X | E | E | E | N/A | E | X | X | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| DATETIME | X | X | X | X | X | X | X | X | X | E | | | | N/A | X | X | X | X | X | X |
| DATETIME | X | X | X | X | X | X | X | X | X | E | E | E | E | N/A | X | X | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| INTERVAL | X | X | X | X | X | X | X | X | X | E | | | | X | N/A | X | X | X | X | X |
| INTERVAL | X | X | X | X | X | X | X | X | X | E | X | X | X | X | N/A | X | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
| GEO_POINT | X | X | X | X | X | X | X | X | X | | X | X | X | X | X | N/A | X | X | X | X |
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
Expand Down Expand Up @@ -236,8 +236,7 @@ Numeric values ranged from -2147483648 to +2147483647 are recognized as integer
Date and Time Data Types
========================

The date and time data types are the types that represent temporal values and SQL plugin supports types including DATE, TIME, DATETIME, TIMESTAMP and INTERVAL. By default, the OpenSearch DSL uses date type as the only date and time related type, which has contained all information about an absolute time point. To integrate with SQL language, each of the types other than timestamp is holding part of temporal or timezone information, and the usage to explicitly clarify the date and time types is reflected in the datetime functions (see `Functions <functions.rst>`_ for details), where some functions might have restrictions in the input argument type.

The date and time data types are the types that represent temporal values and SQL plugin supports types including ``DATE``, ``TIME``, ``DATETIME``, ``TIMESTAMP`` and ``INTERVAL``. By default, the OpenSearch DSL uses ``date`` type as the only date and time related type, which has contained all information about an absolute time point. To integrate with SQL language, each of the types other than timestamp is holding part of temporal or timezone information, and the usage to explicitly clarify the date and time types is reflected in the datetime functions (see `Functions <functions.rst>`_ for details), where some functions might have restrictions in the input argument type.
Yury-Fridlyand marked this conversation as resolved.
Show resolved Hide resolved
Yury-Fridlyand marked this conversation as resolved.
Show resolved Hide resolved

Date
----
Expand Down Expand Up @@ -299,7 +298,7 @@ Interval data type represents a temporal duration or a period. The syntax is as
| Interval | INTERVAL expr unit |
+----------+--------------------+

The expr is any expression that can be iterated to a quantity value eventually, see `Expressions <expressions.rst>`_ for details. The unit represents the unit for interpreting the quantity, including MICROSECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER and YEAR.The INTERVAL keyword and the unit specifier are not case sensitive. Note that there are two classes of intervals. Year-week intervals can store years, quarters, months and weeks. Day-time intervals can store days, hours, minutes, seconds and microseconds. Year-week intervals are comparable only with another year-week intervals. These two types of intervals can only comparable with the same type of themselves.
The expr is any expression that can be iterated to a quantity value eventually, see `Expressions <expressions.rst>`_ for details. The unit represents the unit for interpreting the quantity, including ``MICROSECOND``, ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``QUARTER`` and ``YEAR``. The ``INTERVAL`` keyword and the unit specifier are not case sensitive. Note that there are two classes of intervals. Year-week intervals can store years, quarters, months and weeks. Day-time intervals can store days, hours, minutes, seconds and microseconds. Year-week intervals are comparable only with another year-week intervals. These two types of intervals can only comparable with the same type of themselves.


Conversion between date and time types
Expand All @@ -320,7 +319,7 @@ Conversion from DATE
Conversion from TIME
>>>>>>>>>>>>>>>>>>>>

- Time value cannot be converted to any other date and time types since it does not contain any date information, so it is not meaningful to give no date info to a date/datetime/timestamp instance.
- When time value converted to any other datetime types, the date part of the new value is filled up with today's date. For example, a time value converted to date would produce today's date (like `CURDATE` function); a time value X converted to a timestamp would produce today's date at time X.
Yury-Fridlyand marked this conversation as resolved.
Show resolved Hide resolved


Conversion from DATETIME
Expand Down Expand Up @@ -354,18 +353,94 @@ A string can also represent and be converted to date and time types (except to i
| True | False | True |
+------------------------------------------------------------+-------------------------------------+----------------------------------+

Please, see `more examples here <../dql/expressions.rst#toc-entry-15>`_.

Date formats
------------

SQL plugin supports all named formats for OpenSearch ``date`` data type, custom formats and their combination. Please, refer to `OpenSearch docs <https://opensearch.org/docs/latest/field-types/supported-field-types/date/>`_ for format description.
Plugin detects which type of data is stored in ``date`` field according to formats given and returns results in the corresponding SQL types.
Given an index with the following mapping.

.. code-block:: json

{
"mappings" : {
"properties" : {
"date1" : {
"type" : "date",
"format": "yyyy-MM-dd"
},
"date2" : {
"type" : "date",
"format": "date_time_no_millis"
},
"date3" : {
"type" : "date",
"format": "hour_minute_second"
},
"date4" : {
"type" : "date"
},
"date5" : {
"type" : "date",
"format": "yyyy-MM-dd || time"
}
}
}
}

Querying such index will provide a response with ``schema`` block as shown below.

.. code-block:: json

{
"query" : "SELECT * from date_formats LIMIT 0;"
}

.. code-block:: json

{
"schema": [
{
"name": "date5",
"type": "timestamp"
},
{
"name": "date4",
"type": "timestamp"
},
{
"name": "date3",
"type": "time"
},
{
"name": "date2",
"type": "timestamp"
},
{
"name": "date1",
"type": "date"
},
],
"datarows": [],
"total": 0,
"size": 0,
"status": 200
}

String Data Types
=================

A string is a sequence of characters enclosed in either single or double quotes. For example, both 'text' and "text" will be treated as string literal. To use quote characters in a string literal, you can use two quotes of the same type as the enclosing quotes::
A string is a sequence of characters enclosed in either single or double quotes. For example, both 'text' and "text" will be treated as string literal. To use quote characters in a string literal, you can use two quotes of the same type as the enclosing quotes or a backslash symbol (``\``)::
Yury-Fridlyand marked this conversation as resolved.
Show resolved Hide resolved

os> SELECT 'hello', "world", '"hello"', "'world'", '''hello''', """world"""
os> SELECT 'hello', "world", '"hello"', "'world'", '''hello''', """world""", 'I\'m', "I\"m"
fetched rows / total rows = 1/1
+-----------+-----------+-------------+-------------+---------------+---------------+
| 'hello' | "world" | '"hello"' | "'world'" | '''hello''' | """world""" |
|-----------+-----------+-------------+-------------+---------------+---------------|
| hello | world | "hello" | 'world' | 'hello' | "world" |
+-----------+-----------+-------------+-------------+---------------+---------------+
+-----------+-----------+-------------+-------------+---------------+---------------+----------+----------+
| 'hello' | "world" | '"hello"' | "'world'" | '''hello''' | """world""" | 'I\'m' | "I\"m" |
|-----------+-----------+-------------+-------------+---------------+---------------+----------+----------|
| hello | world | "hello" | 'world' | 'hello' | "world" | I'm | I"m |
+-----------+-----------+-------------+-------------+---------------+---------------+----------+----------+

Boolean Data Types
==================
Expand Down