Skip to content

Commit 9e3fa72

Browse files
Yury-Fridlyandforestmveymatthewryanwells
authored and
MitchellGale
committed
Update docs to reflect recent changes. (#285) (opensearch-project#1826)
* Update docs. * Apply suggestions from code review * Add example of quote escaping. * Update docs/user/general/datatypes.rst * Update docs/user/general/datatypes.rst --------- Signed-off-by: Yury-Fridlyand <[email protected]> Co-authored-by: Forest Vey <[email protected]> Co-authored-by: Matthew Wells <[email protected]> Signed-off-by: Mitchell Gale <[email protected]>
1 parent 43fbadc commit 9e3fa72

File tree

2 files changed

+92
-17
lines changed

2 files changed

+92
-17
lines changed

‎docs/user/dql/expressions.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ Here is an example for different type of comparison operators::
160160
+---------+----------+---------+----------+----------+---------+
161161

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

165165
os> SELECT current_time() > current_date() AS `now.time > today`, typeof(current_time()) AS `now.time.type`, typeof(current_date()) AS `now.date.type`;
166166
fetched rows / total rows = 1/1

‎docs/user/general/datatypes.rst‎

Lines changed: 91 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -155,15 +155,15 @@ The following matrix illustrates the conversions allowed by our query engine for
155155
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
156156
| STRING | E | E | E | E | E | E | IE | X | X | N/A | IE | IE | IE | IE | X | X | X | X | X | X |
157157
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
158-
| TIMESTAMP | X | X | X | X | X | X | X | X | X | E | N/A | | | X | X | X | X | X | X | X |
158+
| TIMESTAMP | X | X | X | X | X | X | X | X | X | E | N/A | IE | IE | IE | X | X | X | X | X | X |
159159
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
160-
| DATE | X | X | X | X | X | X | X | X | X | E | | N/A | | X | X | X | X | X | X | X |
160+
| DATE | X | X | X | X | X | X | X | X | X | E | E | N/A | IE | E | X | X | X | X | X | X |
161161
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
162-
| TIME | X | X | X | X | X | X | X | X | X | E | | | N/A | X | X | X | X | X | X | X |
162+
| TIME | X | X | X | X | X | X | X | X | X | E | E | E | N/A | E | X | X | X | X | X | X |
163163
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
164-
| DATETIME | X | X | X | X | X | X | X | X | X | E | | | | N/A | X | X | X | X | X | X |
164+
| DATETIME | X | X | X | X | X | X | X | X | X | E | E | E | E | N/A | X | X | X | X | X | X |
165165
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
166-
| INTERVAL | X | X | X | X | X | X | X | X | X | E | | | | X | N/A | X | X | X | X | X |
166+
| INTERVAL | X | X | X | X | X | X | X | X | X | E | X | X | X | X | N/A | X | X | X | X | X |
167167
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
168168
| GEO_POINT | X | X | X | X | X | X | X | X | X | | X | X | X | X | X | N/A | X | X | X | X |
169169
+--------------+------+-------+---------+------+-------+--------+---------+--------------+------+--------+-----------+------+------+----------+----------+-----------+-----+--------+-----------+---------+
@@ -236,8 +236,7 @@ Numeric values ranged from -2147483648 to +2147483647 are recognized as integer
236236
Date and Time Data Types
237237
========================
238238

239-
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.
240-
239+
The datetime types supported by the SQL plugin are ``DATE``, ``TIME``, ``DATETIME``, ``TIMESTAMP``, and ``INTERVAL``, with date and time being used to represent temporal values. By default, the OpenSearch DSL uses ``date`` type as the only date and time related type as it contains all information about an absolute time point. To integrate with SQL language each of the types other than timestamp hold part of the temporal or timezone information. This information can be used to explicitly clarify the date and time types reflected in the datetime functions (see `Functions <functions.rst>`_ for details), where some functions might have restrictions in the input argument type.
241240

242241
Date
243242
----
@@ -299,7 +298,7 @@ Interval data type represents a temporal duration or a period. The syntax is as
299298
| Interval | INTERVAL expr unit |
300299
+----------+--------------------+
301300

302-
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.
301+
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.
303302

304303

305304
Conversion between date and time types
@@ -320,7 +319,7 @@ Conversion from DATE
320319
Conversion from TIME
321320
>>>>>>>>>>>>>>>>>>>>
322321

323-
- 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.
322+
- When time value is converted to any other datetime types, the date part of the new value is filled up with today's date, like with the `CURDATE` function. For example, a time value X converted to a timestamp would produce today's date at time X.
324323

325324

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

356+
Please, see `more examples here <../dql/expressions.rst#toc-entry-15>`_.
357+
358+
Date formats
359+
------------
360+
361+
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.
362+
Plugin detects which type of data is stored in ``date`` field according to formats given and returns results in the corresponding SQL types.
363+
Given an index with the following mapping.
364+
365+
.. code-block:: json
366+
367+
{
368+
"mappings" : {
369+
"properties" : {
370+
"date1" : {
371+
"type" : "date",
372+
"format": "yyyy-MM-dd"
373+
},
374+
"date2" : {
375+
"type" : "date",
376+
"format": "date_time_no_millis"
377+
},
378+
"date3" : {
379+
"type" : "date",
380+
"format": "hour_minute_second"
381+
},
382+
"date4" : {
383+
"type" : "date"
384+
},
385+
"date5" : {
386+
"type" : "date",
387+
"format": "yyyy-MM-dd || time"
388+
}
389+
}
390+
}
391+
}
392+
393+
Querying such index will provide a response with ``schema`` block as shown below.
394+
395+
.. code-block:: json
396+
397+
{
398+
"query" : "SELECT * from date_formats LIMIT 0;"
399+
}
400+
401+
.. code-block:: json
402+
403+
{
404+
"schema": [
405+
{
406+
"name": "date5",
407+
"type": "timestamp"
408+
},
409+
{
410+
"name": "date4",
411+
"type": "timestamp"
412+
},
413+
{
414+
"name": "date3",
415+
"type": "time"
416+
},
417+
{
418+
"name": "date2",
419+
"type": "timestamp"
420+
},
421+
{
422+
"name": "date1",
423+
"type": "date"
424+
},
425+
],
426+
"datarows": [],
427+
"total": 0,
428+
"size": 0,
429+
"status": 200
430+
}
431+
357432
String Data Types
358433
=================
359434

360-
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::
435+
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 (``\``)::
361436

362-
os> SELECT 'hello', "world", '"hello"', "'world'", '''hello''', """world"""
437+
os> SELECT 'hello', "world", '"hello"', "'world'", '''hello''', """world""", 'I\'m', 'I''m', "I\"m"
363438
fetched rows / total rows = 1/1
364-
+-----------+-----------+-------------+-------------+---------------+---------------+
365-
| 'hello' | "world" | '"hello"' | "'world'" | '''hello''' | """world""" |
366-
|-----------+-----------+-------------+-------------+---------------+---------------|
367-
| hello | world | "hello" | 'world' | 'hello' | "world" |
368-
+-----------+-----------+-------------+-------------+---------------+---------------+
439+
+-----------+-----------+-------------+-------------+---------------+---------------+----------+----------+----------+
440+
| 'hello' | "world" | '"hello"' | "'world'" | '''hello''' | """world""" | 'I\'m' | 'I''m' | "I\"m" |
441+
|-----------+-----------+-------------+-------------+---------------+---------------+----------+----------+----------|
442+
| hello | world | "hello" | 'world' | 'hello' | "world" | I'm | I'm | I"m |
443+
+-----------+-----------+-------------+-------------+---------------+---------------+----------+----------+----------+
369444

370445
Boolean Data Types
371446
==================

0 commit comments

Comments
 (0)