SQL Capabilities

DML allows you to update and query data stored in OmniSci.
See Using Geospatial Objects: Geospatial Functions for details on geospatial functions.
INSERT
Use for single-row ad hoc inserts. (When inserting many rows, use the more efficient COPY command.)
1
INSERT INTO <destination_table> VALUES (<value>, ...);
Copied!
1
INSERT INTO <table> (<column>, ...) VALUES (value, ...);
Copied!
Examples
1
CREATE TABLE foo (a INT, b FLOAT, c TEXT, d TIMESTAMP);
2
INSERT INTO foo VALUES (NULL, 3.1415, 'xyz', '2015-05-11 211720');
Copied!
You can also insert into a table as SELECT, as shown in the following examples:
Example 1
Example 2
Example 3
Example 4
1
INSERT INTO destination_table SELECT * FROM source_table;
Copied!
1
INSERT INTO destination_table (id, name, age, gender) SELECT * FROM source_table;
Copied!
1
INSERT INTO destination_table (name, gender, age, id) SELECT name, gender, age, id  FROM source_table;
Copied!
1
INSERT INTO votes_summary (vote_id, vote_count) SELECT vote_id, sum(*) FROM votes GROUP_BY vote_id;
Copied!
You can insert array literals into array columns. The inserts in the following example each have three array values, and demonstrate how you can:
Create a table with variable-length and fixed-length array columns.
Insert NULL arrays into these colums.
Specify and insert array literals using {...} or ARRAY[...] syntax.
Insert empty variable-length arrays using{} and ARRAY[] syntax.
Insert array values that contain NULL elements.
1
CREATE TABLE ar (ai INT[], af FLOAT[], ad2 DOUBLE[2]); 
2
INSERT INTO ar VALUES ({1,2,3},{4.0,5.0},{1.2,3.4}); 
3
INSERT INTO ar VALUES (ARRAY[NULL,2],NULL,NULL); 
4
INSERT INTO ar VALUES (NULL,{},{2.0,NULL});
Copied!
Default Values
If you create a table with column that has a default value, or alter a table to add a column with a default value, using the INSERT command creates a record that includes the default value if it is omitted from the INSERT. For example, assume a table created as follows:
1
CREATE TABLE tbl (
2
   id INTEGER NOT NULL, 
3
   name TEXT NOT NULL DEFAULT 'John Doe', 
4
   age SMALLINT NOT NULL);
Copied!
If you omit the name column from an INSERT or INSERT FROM SELECT statement, the missing value for column name is set to 'John Doe'.
INSERT INTO tbl (id, age) VALUES (1, 36); creates the record 1|'John Doe'|36 .
INSERT INTO tbl (id, age) SELECT id, age FROM old_tbl; also sets all the name values to John Doe .
SELECT
1
query:
2
  |   WITH withItem [ , withItem ]* query
3
  |   {
4
          select
5
      }
6
      [ ORDER BY orderItem [, orderItem ]* ]
7
      [ LIMIT [ start, ] { count | ALL } ]
8
      [ OFFSET start { ROW | ROWS } ]
9
​
10
withItem:
11
      name
12
      [ '(' column [, column ]* ')' ]
13
      AS '(' query ')'
14
​
15
orderItem:
16
      expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ]
17
​
18
select:
19
      SELECT [ DISTINCT ] [/*+ hints */]
20
          { * | projectItem [, projectItem ]* }    
21
      FROM tableExpression
22
      [ WHERE booleanExpression ]
23
      [ GROUP BY { groupItem [, groupItem ]* } ]
24
      [ HAVING booleanExpression ]
25
      [ WINDOW window_name AS ( window_definition ) [, ...] ]
26
​
27
projectItem:
28
      expression [ [ AS ] columnAlias ]
29
  |   tableAlias . *
30
​
31
tableExpression:
32
      tableReference [, tableReference ]*
33
  |   tableExpression [ ( LEFT ) [ OUTER ] ] JOIN tableExpression [ joinCondition ]
34
​
35
joinCondition:
36
      ON booleanExpression
37
  |   USING '(' column [, column ]* ')'
38
​
39
tableReference:
40
      tablePrimary
41
      [ [ AS ] alias ]
42
​
43
tablePrimary:
44
      [ catalogName . ] tableName
45
  |   '(' query ')'
46
​
47
groupItem:
48
      expression
49
  |   '(' expression [, expression ]* ')'
Copied!
For more information, see SELECT.
ORDER BY
Sort order defaults to ascending (ASC).
Sorts null values after non-null values by default in an ascending sort, before non-null values in a descending sort. For any query, you can use NULLS FIRST to sort null values to the top of the results or NULLS LAST to sort null values to the bottom of the results.
Allows you to use a positional reference to choose the sort column. For example, the command SELECT colA,colB FROM table1 ORDER BY 2 sorts the results on colB because it is in position 2.
SELECT Hints
You can specify hints in SELECT statements. For example, you could use the /*+ cpu_mode */ hint, which forces query execution on CPU, when:
You know in advance that that running on CPU is more efficient. 
You want to avoid overhead related to a query being punted from GPU to CPU because of a potential runtime failure. 
Syntax
1
SELECT /*+ hint */ FROM ...;
Copied!
SELECT hints must appear first, immediately after the SELECT statement; otherwise, the query fails.
SQL hints affect the query block in which they appear. For example, if you define the columnar_result hint in a subquery SELECT clause, it affects only the subquery.
Here the  columnar_result hint is applied only to the inner query block.
1
SELECT COUNT(1) FROM (SELECT /*+ columnar_result */ x FROM test) t;
Copied!
UPDATE
1
UPDATE table_name SET assign [, assign ]* [ WHERE booleanExpression ]
Copied!
Changes the values of the specified columns based on the assign argument (identifier=expression) in all rows that satisfy the condition in the WHERE clause.
Example
1
UPDATE UFOs SET shape='ovate' where shape='eggish';
Copied!
Currently, OmniSci does not support updating a geo column type (POINT, LINESTRING, POLYGON, or MULTIPOLYGON) in a table.
Update Via Subquery
You can update a table via subquery, which allows you to update based on calculations performed on another table.
Examples
Example 1
Example 2
Example 3
1
UPDATE test_facts SET lookup_id = (SELECT SAMPLE(test_lookup.id) 
2
FROM test_lookup WHERE test_lookup.val = test_facts.val);
Copied!
1
UPDATE test_facts SET val = val+1, lookup_id = (SELECT SAMPLE(test_lookup.id)
2
FROM test_lookup WHERE test_lookup.val = test_facts.val);
Copied!
1
UPDATE test_facts SET lookup_id = (SELECT SAMPLE(test_lookup.id) 
2
FROM test_lookup WHERE test_lookup.val = test_facts.val) WHERE id < 10;
Copied!
DELETE
1
DELETE FROM table_name [ * ] [ [ AS ] alias ]
2
[ WHERE condition ]
Copied!
Deletes rows that satisfy the WHERE clause from the specified table. If the WHERE clause is absent, all rows in the table are deleted, resulting in a valid but empty table.
EXPLAIN
Shows generated Intermediate Representation (IR) code, identifying whether it is executed on GPU or CPU. This is primarily used internally by OmniSci to monitor behavior.
1
EXPLAIN <STMT>
Copied!
For example, when you use the EXPLAIN command on a basic statement, the utility returns 90 lines of IR code that is not meant to be human readable. However, at the top of the listing, a heading indicates whether it is IR for the CPU or IR for the GPU, which can be useful to know in some situations.
EXPLAIN CALCITE
Returns a relational algebra tree describing the high-level plan to execute the statement.
1
EXPLAIN CALCITE <STMT>
Copied!
The table below lists the relational algebra classes used to describe the execution plan for a SQL statement.
Method
Description
LogicalAggregate
Operator that eliminates duplicates and computes totals.
LogicalCalc
Expression that computes project expressions and also filters.
LogicalChi
Operator that converts a stream to a relation.
LogicalCorrelate
Operator that performs nested-loop joins.
LogicalDelta
Operator that converts a relation to a stream.
LogicalExchange
Expression that imposes a particular distribution on its input without otherwise changing its content.
LogicalFilter
Expression that iterates over its input and returns elements for which a condition evaluates to true.
LogicalIntersect
Expression that returns the intersection of the rows of its inputs.
LogicalJoin
Expression that combines two relational expressions according to some condition.
LogicalMatch
Expression that represents a MATCH_RECOGNIZE node.
LogicalMinus
Expression that returns the rows of its first input minus any matching rows from its other inputs. Corresponds to the SQL EXCEPT operator.
LogicalProject
Expression that computes a set of ‘select expressions’ from its input relational expression.
LogicalSort
Expression that imposes a particular sort order on its input without otherwise changing its content.
LogicalTableFunctionScan
Expression that calls a table-valued function.
LogicalTableModify
Expression that modifies a table. Similar to TableScan, but represents a request to modify a table instead of read from it.
LogicalTableScan
Reads all the rows from a RelOptTable.
LogicalUnion
Expression that returns the union of the rows of its inputs, optionally eliminating duplicates.
LogicalValues
Expression for which the value is a sequence of zero or more literal row values.
LogicalWindow
Expression representing a set of window aggregates. See Window Functions​
For example, a SELECT statement is described as a table scan and projection.
1
omnisql> EXPLAIN CALCITE (SELECT * FROM movies);
2
Explanation
3
LogicalProject(movieId=[$0], title=[$1], genres=[$2])
4
   LogicalTableScan(TABLE=[[CATALOG, omnisci, MOVIES]])
Copied!
If you add a sort order, the table projection is folded under a LogicalSort procedure.
1
omnisql> EXPLAIN calcite (SELECT * FROM movies ORDER BY title);
2
Explanation
3
LogicalSort(sort0=[$1], dir0=[ASC])
4
   LogicalProject(movieId=[$0], title=[$1], genres=[$2])
5
      LogicalTableScan(TABLE=[[CATALOG, omnisci, MOVIES]])
Copied!
When the SQL statement is simple, the EXPLAIN CALCITE version is actually less “human readable.” EXPLAIN CALCITE is more useful when you work with more complex SQL statements, like the one that follows. This query performs a scan on the BOOK table before scanning the BOOK_ORDER table.
1
omnisql> EXPLAIN calcite SELECT bc.firstname, bc.lastname, b.title, bo.orderdate, s.name
2
FROM book b, book_customer bc, book_order bo, shipper s
3
WHERE bo.cust_id = bc.cust_id AND b.book_id = bo.book_id AND bo.shipper_id = s.shipper_id
4
AND s.name = 'UPS';
5
Explanation
6
LogicalProject(firstname=[$5], lastname=[$6], title=[$2], orderdate=[$11], name=[$14])
7
    LogicalFilter(condition=[AND(=($9, $4), =($0, $8), =($10, $13), =($14, 'UPS'))])
8
        LogicalJoin(condition=[true], joinType=[INNER])
9
            LogicalJoin(condition=[true], joinType=[INNER])
10
                LogicalJoin(condition=[true], joinType=[INNER])
11
                    LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK]])
12
                    LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK_CUSTOMER]])
13
                LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK_ORDER]])
14
            LogicalTableScan(TABLE=[[CATALOG, omnisci, SHIPPER]])
Copied!
Revising the original SQL command results in a more natural selection order and a more performant query.
1
omnisql> EXPLAIN calcite SELECT bc.firstname, bc.lastname, b.title, bo.orderdate, s.name
2
FROM book_order bo, book_customer bc, book b, shipper s
3
WHERE bo.cust_id = bc.cust_id AND bo.book_id = b.book_id AND bo.shipper_id = s.shipper_id
4
AND s.name = 'UPS';
5
Explanation
6
LogicalProject(firstname=[$10], lastname=[$11], title=[$7], orderdate=[$3], name=[$14])
7
    LogicalFilter(condition=[AND(=($1, $9), =($5, $0), =($2, $13), =($14, 'UPS'))])
8
        LogicalJoin(condition=[true], joinType=[INNER])
9
            LogicalJoin(condition=[true], joinType=[INNER])
10
                LogicalJoin(condition=[true], joinType=[INNER])
11
                  LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK_ORDER]])
12
                  LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK_CUSTOMER]])
13
                LogicalTableScan(TABLE=[[CATALOG, omnisci, BOOK]])
14
            LogicalTableScan(TABLE=[[CATALOG, omnisci, SHIPPER]])
Copied!
SHOW
Use SHOW commands to get information about databases, tables, and user sessions.
Command
Description
SHOW CREATE TABLE
Shows the CREATE TABLE statement that could have been used to create the table.
SHOW CREATE TABLE omnisci_states;
CREATE TABLE omnisci_states (
 id TEXT ENCODING DICT(32),
 abbr TEXT ENCODING DICT(32),
 name TEXT ENCODING DICT(32),
 omnisci_geo GEOMETRY(MULTIPOLYGON, 4326) NOT NULL);
SHOW DATABASES
Retrieve the databases accessible for the current user, showing the database name and owner.
Database Owner
omnisci admin
2004_zipcodes admin
game_results jane
signals jason
...
SHOW [EFFECTIVE] POLICIES <name>;
Displays a list of all row-level security (RLS) policies that exist for a user or role; admin rights are required. If EFFECTIVE is used, the list also includes any policies that exist for all roles that apply to the requested user or role.
SHOW QUERIES
Returns a list of queued queries in the system; information includes session ID, status, query string, account login name, client address, database name, and device type (CPU or GPU). See SHOW QUERIES Example to see output.
​
Admin users can see and interrupt all queries, and non-Admin users can see and interrupt only their own queries

NOTE: SHOW QUERIES is only available if the runtime query interrupt parameter (enable-runtime-query-interrupt) is set.
SHOW [EFFECTIVE] ROLES <name>
If included with a name, lists the roles  granted directly to a user or role. SHOW EFFECTIVE ROLES with a name lists the roles directly granted to a user or role, and also lists the roles indirectly inherited through the directly granted roles.
​
If the user name or role name is omitted, then a regular user sees their own roles, and a superuser sees a list of all roles existing in the system.
SHOW TABLE DETAILS [<table-name>, <table-name>, ...]
Displays storage-related information for a table, such as the table ID/name, number of data/metadata files used by the table, total size of data/metadata files, and table epoch values.
You can see table details for all tables that you have access to in the current database, or for only those tables you specify.
See SHOW TABLE DETAILS Examples to see example output.
SHOW TABLES
Retrieve the tables accessible for the current user.
SHOW TABLES;
table_name
omnisci_states
omnisci_counties
omnisci_countries
streets_nyc
streets_miami
...
SHOW USER DETAILS
Show name, ID, superuser status, default database, and login permission status for all or specified database users.
Show details for all users:
omnisql> SHOW USER DETAILS;
NAME |ID|IS_SUPER|DEFAULT_DB|CAN_LOGIN
admin|0 |true | |true
alice|1 |true |omnisci |true
bob |2 |true | |false
chuck|3 |false |omnisci |true
Show details for users bob and alice:
omnisql> SHOW USER DETAILS bob,alice;
NAME |ID|IS_SUPER|DEFAULT_DB|CAN_LOGIN
bob |2 |true | |false
alice|1 |true |omnisci |true
SHOW USER SESSIONS
Retrieve all persisted user sessions, showing the session ID, user login name, client address, and database name. Admin or superuser privileges required.
SHOW USER SESSIONS;
session_id login_name client_address db_name
453-X6ds mike http:198.51.100.1 game_results
453-0t2r erin http:198.51.100.11 game_results
421-B64s shauna http:198.51.100.43 game_results
213-06dw ahmed http:198.51.100.12 signals
333-R28d cat http:198.51.100.233 signals
497-Xyz6 inez http:198.51.100.5 ships
...
SHOW QUERIES Example
Show the queries in the queue:
1
show queries;
2
query_session_id|current_status|submitted          |query_str                                                   |login_name|client_address     |db_name   |exec_device_type
3
834-8VAA        |Pending       |2020-05-06 08:21:15|select d_date_sk, count(1) from date_dim group by d_date_sk;|admin     |tcp:localhost:48596|tpcds_sf10|CPU
4
826-CLKk        |Running       |2020-05-06 08:20:57|select count(1) from store_sales, store_returns;            |admin     |tcp:localhost:48592|tpcds_sf10|CPU
5
828-V6s7        |Pending       |2020-05-06 08:21:13|select count(1) from store_sales;                           |admin     |tcp:localhost:48594|tpcds_sf10|GPU
6
946-rtJ7        |Pending       |2020-05-06 08:20:58|select count(1) from item;                                  |admin     |tcp:localhost:48610|tpcds_sf10|GPU
Copied!
To interrupt a query in the queue, see KILL QUERY.
SHOW TABLE DETAILS Examples
Show details for all tables you have access to:
1
omnisql> show table details;
2
table_id|table_name       |column_count|is_sharded_table|shard_count|max_rows           |fragment_size|max_rollback_epochs|min_epoch|max_epoch|min_epoch_floor|max_epoch_floor|metadata_file_count|total_metadata_file_size|total_metadata_page_count|total_free_metadata_page_count|data_file_count|total_data_file_size|total_data_page_count|total_free_data_page_count
3
1       |omnisci_states   |11          |false           |0          |4611686018427387904|32000000     |-1                 |1        |1        |0              |0              |1                  |16777216                |4096                     |4082                          |1              |536870912           |256                  |242
4
2       |omnisci_counties |13          |false           |0          |4611686018427387904|32000000     |-1                 |1        |1        |0              |0              |1                  |16777216                |4096                     |NULL                          |1              |536870912           |256                  |NULL
5
3       |omnisci_countries|71          |false           |0          |4611686018427387904|32000000     |-1                 |1        |1        |0              |0              |1                  |16777216                |4096                     |4022                          |1              |536870912           |256                  |182
Copied!
Show details for table omnisci_states:
1
omnisql> show table details omnisci_states;
2
table_id|table_name    |column_count|is_sharded_table|shard_count|max_rows           |fragment_size|max_rollback_epochs|min_epoch|max_epoch|min_epoch_floor|max_epoch_floor|metadata_file_count|total_metadata_file_size|total_metadata_page_count|total_free_metadata_page_count|data_file_count|total_data_file_size|total_data_page_count|total_free_data_page_count
3
1       |omnisci_states|11          |false           |0          |4611686018427387904|32000000     |-1                 |1        |1        |0              |0              |1                  |16777216                |4096                     |4082                          |1              |536870912           |256                  |242
Copied!
The number of columns returned includes system columns. As a result, the number of columns in column_count can be up to two greater than the number of columns created by the user.
KILL QUERY
Interrupt a queued query. Specify the query by using its session ID.
To see the queries in the queue, use the SHOW QUERIES command:
1
show queries;
2
query_session_id|current_status      |executor_id|submitted     |query_str       |login_name|client_address            |db_name|exec_device_type
3
713-t1ax        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |John      |http:::1                  |omnisci|GPU
4
491-xpfb        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |Patrick   |http:::1                  |omnisci|GPU
5
451-gp2c        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |John      |http:::1                  |omnisci|GPU
6
190-5pax        |PENDING_EXECUTOR    |1          |2021-08-03 ...|SELECT ...      |Cavin     |http:::1                  |omnisci|GPU
7
720-nQtV        |RUNNING_QUERY_KERNEL|2          |2021-08-03 ...|SELECT ...      |Cavin     |tcp:::ffff:127.0.0.1:50142|omnisci|GPU
8
947-ooNP        |RUNNING_IMPORTER    |0          |2021-08-03 ...|IMPORT_GEO_TABLE|Rio       |tcp:::ffff:127.0.0.1:47314|omnisci|CPU
Copied!
To interrupt the last query in the list (ID 946-ooNP):
1
kill query '946-ooNP'
Copied!
Showing the queries again indicates that 946-ooNP has been deleted:
1
show queries;
2
query_session_id|current_status      |executor_id|submitted     |query_str       |login_name|client_address            |db_name|exec_device_type
3
713-t1ax        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |John      |http:::1                  |omnisci|GPU
4
491-xpfb        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |Patrick   |http:::1                  |omnisci|GPU
5
451-gp2c        |PENDING_QUEUE       |0          |2021-08-03 ...|SELECT ...      |John      |http:::1                  |omnisci|GPU
6
190-5pax        |PENDING_EXECUTOR    |1          |2021-08-03 ...|SELECT ...      |Cavin     |http:::1                  |omnisci|GPU
7
720-nQtV        |RUNNING_QUERY_KERNEL|2          |2021-08-03 ...|SELECT ...      |Cavin     |tcp:::ffff:127.0.0.1:50142|omnisci|GPU
Copied!
KILL QUERY is only available if the runtime query interrupt parameter (enable-runtime-query-interrupt) is set.
Interrupting a query in ‘PENDING_QUEUE’ status is supported in both distributed and single-server mode.
To enable query interrupt for tables imported from data files in local storage, set enable_non_kernel_time_query_interrupt to TRUE. (It is enabled by default.)
ALTER SYSTEM CLEAR
Clear CPU, GPU, or RENDER memory. Available to super users only.
1
ALTER SYSTEM CLEAR (CPU|GPU|RENDER) MEMORY
Copied!
Examples
1
ALTER SYSTEM CLEAR CPU MEMORY
Copied!
1
ALTER SYSTEM CLEAR GPU MEMORY
Copied!
1
ALTER SYSTEM CLEAR RENDER MEMORY
Copied!
Generally, the server handles memory management, and you do not need to use this command. If you are having unexpected memory issues, try clearing the memory to see if performance improves.
Window Functions
Window functions allow you to work with a subset of rows related to the currently selected row. For a given dimension, you can find the most associated dimension by some other measure (for example, number of records or sum of revenue).
Window functions must always contain an OVER clause. The OVER clause splits up the rows of the query for processing by the window function.
The PARTITION BY list divides the rows into groups that share the same values of the PARTITION BY expression(s). For each row, the window function is computed using all rows in the same partition as the current row.
Rows that have the same value in the ORDER BY clause are considered peers. The ranking functions give the same answer for any two peer rows.
Function
Description
row_number()
Number of the current row within the partition, counting from 1.
rank()
Rank of the current row with gaps. Equal to the row_number of its first peer.
dense_rank()
Rank of the current row without gaps. This function counts peer groups.
percent_rank()
Relative rank of the current row: (rank-1)/(total rows-1).
cume_dist()
Cumulative distribution value of the current row: (number of rows preceding or peers of the current row)/(total rows)
ntile(num_buckets)
Subdivide the partition into buckets. If the total number of rows is divisible by num_buckets, each bucket has a equal number of rows. If the total is not divisible by num_buckets, the function returns groups of two sizes with a difference of 1.
lag(value, offset)
Returns the value at the row that is offset rows before the current row within the partition
lead(value, offset)
Returns the value at the row that is offset rows after the current row within the partition
first_value(value)
Returns the value from the first row of the window frame (the rows from the start of the partition to the last peer of the current row).
last_value(value)
Returns the value from the last row of the window frame.
Usage Notes
OmniSciDB supports the aggregate functions AVG, MIN, MAX, SUM, and COUNT in window functions.
Window functions where there are expressions (not simple columns) in the window partition and order clause are not currently supported.
Updates on window functions are not currently supported.
Example
This query shows the top airline carrier for each state, based on the number of departures.
1
select origin_state, carrier_name, n 
2
   from (select origin_state, carrier_name, row_number() over(
3
      partition by origin_state order by n desc) as rownum, n 
4
         from (select origin_state, carrier_name, count(*) as n 
5
            from flights_2008_7M where extract(year 
6
               from dep_timestamp) = 2008 
7
   group by origin_state, carrier_name )) where rownum = 1
Copied!
Table Expression and Join Support
1
<table> , <table> WHERE <column> = <column>
2
<table> [ LEFT ] JOIN <table> ON <column> = <column>
Copied!
If a join column name or alias is not unique, it must be prefixed by its table name.
You can use BIGINT, INTEGER, SMALLINT, TINYINT, DATE, TIME, TIMESTAMP, or TEXT ENCODING DICT data types. TEXT ENCODING DICT is the most efficient because corresponding dictionary IDs are sequential and span a smaller range than, for example, the 65,535 values supported in a SMALLINT field. Depending on the number of values in your field, you can use TEXT ENCODING DICT(32) (up to approximately 2,150,000,000 distinct values), TEXT ENCODING DICT(16) (up to 64,000 distinct values), or TEXT ENCODING DICT(8) (up to 255 distinct values). For more information, see Data Types and Fixed Encoding.
Geospatial Joins
By default, a join involving a geospatial operator (such as ST_Contains) utilizes the loop join framework.
To allow all loop joins, set the allow-loop-joins flag to true at either the command line when starting OmniSci, or in omnisci.conf. Running geo join queries without allow-loop-joins set to true results in the following error:
1
Hash join failed: no equijoin expression found.
Copied!
If you set trivial-loop-join-threshold, loop joins are allowed if the inner table has fewer rows than the trivial join loop threshold you specify. The default value is 1,000 rows.
For geospatial joins, the inner table should always be the more complicated primitive. For example, for ST_Contains(polygon, point), the point table should be the outer table and the polygon table should be the inner table.
Geo join best practice is to increase the trivial join loop threshold for the size of the inner table.
When you increase the trivial loop join threshold by 1, you increase the run time by the number of rows in your outer table. For example, if your outer table has 100,000,000 rows, and your trivial loop join threshold is 10, you potentially run 1,000,000,000 operations in the loop. If you increase the loop join to 100, you increase the number of operations run to 10,000,000,000.
Using Joins in a Distributed Environment
You can create joins in a distributed environment in two ways:
Replicate small dimension tables that are used in the join.
Create a shard key on the column used in the join (note that there is a limit of one shard key per table). If the column involved in the join is a TEXT ENCODED field, you must create a SHARED DICTIONARY that references the FACT table key you are using to make the join.
1 small table, 1 large
2 large tables joined with shard key
2 large tables joined on TEXT ENCODED column
1
# Table customers is very small
2
CREATE TABLE sales (
3
id INTEGER,
4
customerid TEXT ENCODING DICT(32),
5
saledate DATE ENCODING DAYS(32),
6
saleamt DOUBLE);
7
​
8
CREATE TABLE customers (
9
id TEXT ENCODING DICT(32),
10
someid INTEGER,
11
name TEXT ENCODING DICT(32))
12
WITH (partitions = 'replicated') #this causes the entire contents of this table to be replicated to each leaf node. Only recommened for small dimension tables.
13
SELECT c.id, c.name from sales s inner join customers c on c.id = s.customerid limit 10;
Copied!
1
CREATE TABLE sales (
2
id INTEGER,
3
customerid BIGINT, #note the numeric datatype, so we don't need to specify a shared dictionary on the customer table
4
saledate DATE ENCODING DAYS(32),
5
saleamt DOUBLE,
6
SHARD KEY (customerid))
7
WITH (SHARD_COUNT = <num gpus in cluster>)
8
​
9
CREATE TABLE customers (
10
id TEXT BIGINT,
11
someid INTEGER,
12
name TEXT ENCODING DICT(32)
13
SHARD KEY (id))
14
WITH (SHARD_COUNT=<num gpus in cluster>);
15
​
16
SELECT c.id, c.name FROM sales s INNER JOIN customers c ON c.id = s.customerid LIMIT 10;
Copied!
1
CREATE TABLE sales (
2
id INTEGER,
3
customerid TEXT ENCODING DICT(32),
4
saledate DATE ENCODING DAYS(32),
5
saleamt DOUBLE,
6
SHARD KEY (customerid))
7
WITH (SHARD_COUNT = <num gpus in cluster>)
8
​
9
#note the difference when customerid is a text encoded field:
10
​
11
CREATE TABLE customers (
12
id TEXT,
13
someid INTEGER,
14
name TEXT ENCODING DICT(32),
15
SHARD KEY (id),
16
SHARED DICTIONARY (id) REFERENCES sales(customerid))
17
WITH (SHARD_COUNT = <num gpus in cluster>)
18
​
19
SELECT c.id, c.name FROM sales s INNER JOIN customers c ON c.id = s.customerid LIMIT 10;
Copied!
The join order for one small table and one large table matters. If you swap the sales and customer tables on the join, it throws an exception stating that table "sales" must be replicated.
Logical Operator Support
Operator
Description
AND
Logical AND
NOT
Negates value
OR
Logical OR
Conditional Expression Support
Expression
Description
CASE WHEN condition THEN result ELSE default END
Case operator
COALESCE(val1, val2, ..)
Returns the first non-null value in the list
Subquery Expression Support
Expression
Description
expr IN (subquery or list of values)
Evaluates whether expr equals any value of the IN list.
expr NOT IN (subquery or list of values)
Evaluates whether expr does not equal any value of the IN list.
Usage Notes
You can use a subquery anywhere an expression can be used, subject to any runtime constraints of that expression. For example, a subquery in a CASE statement must return exactly one row, but a subquery can return multiple values to an IN expression.
You can use a subquery anywhere a table is allowed (for example, FROM subquery), using aliases to name any reference to the table and columns returned by the subquery.
Type Cast Support
Expression
Example
Description
CAST(expr AS type)
CAST(1.25 AS FLOAT)
Converts an expression to another data type
The following table shows cast type conversion support.
FROM/TO:
TINYINT
SMALLINT
INTEGER
BIGINT
FLOAT
DOUBLE
DECIMAL
TEXT
BOOLEAN
DATE
TIME
TIMESTAMP
TINYINT
-
Yes
Yes
Yes
Yes
Yes
Yes
No
No
No
No
n/a
SMALLINT
Yes
-
Yes
Yes
Yes
Yes
Yes
No
No
No
No
n/a
INTEGER
Yes
Yes
-
Yes
Yes
Yes
Yes
No
Yes
No
No
No
BIGINT
Yes
Yes
Yes
-
Yes
Yes
Yes
No
No
No
No
No
FLOAT
Yes
Yes
Yes
Yes
-
Yes
No
No
No
No
No
No
DOUBLE
Yes
Yes
Yes
Yes
Yes
-
No
No
No
No
No
n/a
DECIMAL
Yes
Yes
Yes
Yes
Yes
Yes
-
No
No
No
No
n/a
TEXT
No
No
No
No
No
No
No
-
No
No
No
No
BOOLEAN
No
No
Yes
No
No
No
No
No
-
n/a
n/a
n/a
DATE
No
No
No
No
No
No
No
No
n/a
-
No
Yes
TIME
No
No
No
No
No
No
No
No
n/a
No
-
n/a
TIMESTAMP
No
No
No
No
No
No
No
No
n/a
Yes
No
-
Array Support
OmniSci supports arrays in dictionary-encoded text and number fields (TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, and DOUBLE). Data stored in arrays are not normalized. For example, {green,yellow} is not the same as {yellow,green}. As with many SQL-based services, OmniSci array indexes are 1-based.
OmniSci supports NULL variable-length arrays for all integer and floating-point data types, including dictionary-encoded string arrays. For example, you can insert NULL into BIGINT[ ], DOUBLE[ ], or TEXT[ ] columns. OmniSci supports NULL fixed-length arrays for all integer and floating-point data types, but not for dictionary-encoded string arrays. For example, you can insert NULL into BIGINT[2] DOUBLE[3], but not into TEXT[2] columns.
Expression
Description
​
​
​
​
​
​
​
ArrayCol[n] ...
Returns value(s) from specific location n in the array.
​
​
​
​
​
​
​
UNNEST(ArrayCol)
Extract the values in the array to a set of rows. Requires GROUP BY; projecting UNNEST is not currently supported.
​
​
​
​
​
​
​
test = ANY ArrayCol
ANY compares a scalar value with a single row or set of values in an array, returning results in which at least one item in the array matches. ANY must be preceded by a comparison operator.
​
​
​
​
​
​
​
test = ALL ArrayCol
ALL compares a scalar value with a single row or set of values in an array, returning results in which all records in the array field are compared to the scalar value. ALL must be preceded by a comparison operator.
​
​
​
​
​
​
​
CARDINALITY()
Returns the number of elements in an array. For example: `omnisql> \d arr  CREATE TABLE arr (  sia SMALLINT[])  omnisql> select sia, CARDINALITY(sia) from arr;  sia
EXPR$0  NULL
NULL  {}
0  {NULL}
1  {1}
1  {2,2}
2  {3,3,3}
3`
Examples
The following examples show query results based on the table test_array created with the following statement:
1
CREATE TABLE test_array (name TEXT ENCODING DICT(32),colors TEXT[] ENCODING DICT(32), qty INT[]);
Copied!
Example 1
Example 2
Example 3
Example 4
Example 5
Example 6
1
omnisql> SELECT * FROM test_array;
2
name|colors|qty
3
Banana|{green, yellow}|{1, 2}
4
Cherry|{red, black}|{1, 1}
5
Olive|{green, black}|{1, 0}
6
Onion|{red, white}|{1, 1}
7
Pepper|{red, green, yellow}|{1, 2, 3}
8
Radish|{red, white}|{}
9
Rutabaga|NULL|{}
10
Zucchini|{green, yellow}|{NULL}
Copied!
1
omnisql> SELECT UNNEST(colors) AS c FROM test_array;
2
Exception: UNNEST not supported in the projection list yet.
Copied!
1
omnisql> SELECT UNNEST(colors) AS c, count(*) FROM test_array group by c;
2
c|EXPR$1
3
green|4
4
yellow|3
5
red|4
6
black|2
7
white|2
Copied!
1
omnisql> SELECT name, colors [2] FROM test_array;
2
name|EXPR$1
3
Banana|yellow
4
Cherry|black
5
Olive|black
6
Onion|white
7
Pepper|green
8
Radish|white
9
Rutabaga|NULL
10
Zucchini|yellow
Copied!
1
omnisql> SELECT name, colors FROM test_array WHERE colors[1]='green';
2
name|colors
3
Banana|{green, yellow}
4
Olive|{green, black}
5
Zucchini|{green, yellow}
Copied!
1
omnisql> SELECT * FROM test_array WHERE colors IS NULL;
2
name|colors|qty
3
Rutabaga|NULL|{}
Copied!