Oracle® NoSQL Database SQL Reference for Oracle NoSQL Database Release 19.5 F14605-02 March 2020 Oracle NoSQL Database SQL Reference for Oracle NoSQL Database, Release 19.5 F14605-02 Copyright © 2020, Oracle and/or its affiliates. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or “commercial computer software documentation” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle. Contents 1 Introduction to SQL for Oracle NoSQL Database SQL Program 1-1 EBNF Syntax 1-2 Comments 1-3 Identifiers 1-3 Literals 1-4 Operator Precedence 1-5 Reserved Words 1-5 2 Oracle NoSQL Database Data Model Atomic Data Types 2-1 Complex Data Types 2-3 Wildcard Data Types 2-5 Data Type Hierarchy 2-7 Data Type Definitions 2-9 3 Namespace Management CREATE NAMESPACE Statement 3-1 DROP NAMESPACE Statement 3-2 Namespace Resolution 3-3 Namespace Scoped Privileges 3-3 4 Table Management CREATE REGION Statement 4-1 CREATE TABLE Statement 4-2 Table Hierarchies 4-5 Using the IDENTITY Column 4-6 Sequence Generator 4-8 DROP TABLE Statement 4-9 DROP TABLE Statement 4-10 iii ALTER TABLE Statement 4-10 Altering an IDENTITY Column 4-11 5 SQL Query Management Expressions 5-1 Sequences 5-1 Sequence Types 5-2 Variable Declaration 5-3 SELECT Expression 5-5 FROM Clause 5-5 WHERE Clause 5-7 GROUP BY Clause 5-7 Using Aggregate Functions 5-8 Sequence Aggregate Functions 5-10 ORDER BY Clause 5-11 SELECT Clause 5-13 LIMIT Clause 5-14 OFFSET Clause 5-15 Path Expressions 5-15 Field Step Expressions 5-16 Map-Filter Step Expressions 5-18 Array-Filter Step Expressions 5-20 Array-Slice Step Expressions 5-21 Comparision Expressions 5-23 Logical Operators: AND, OR, and NOT 5-23 IS NULL and IS NOT NULL Operators 5-23 Value Comparison Operators 5-24 Sequence Comparison Operators 5-26 Exists Operator 5-27 Is-Of-Type Operator 5-28 Concatenation Operator 5-29 Arithmetic Expressions 5-29 Primary Expressions 5-30 Parenthesized Expressions 5-31 Constant Expressions 5-31 Column References 5-32 Variable References 5-32 Array and Map Constructors 5-33 Case Expressions 5-34 Cast Expression 5-35 iv Extract Expressions 5-36 Function Calls 5-37 Sequence Transform Expressions 5-38 Joins 5-39 Joining Tables in the Same Table Hierarchy 5-39 Example: Joining Tables 5-43 Left Outer Join (LOJ) 5-44 6 Data Row Management INSERT Statement 6-1 Inserting Rows with an IDENTITY Column 6-4 DELETE Statement 6-5 UPDATE Statement 6-6 Update Clauses 6-7 SET Clause 6-7 ADD Clause 6-8 PUT Clause 6-9 REMOVE Clause 6-9 SET TTL Clause 6-10 Updating rows with an IDENTITY Column 6-10 Example: Updating Rows 6-10 Example: Updating JSON Data 6-13 Example: Updating TTL 6-14 Example: Updating IDENTITY defined as GENERATED ALWAYS 6-14 Example: Updating IDENTITY defined as GENERATED BY DEFAULT 6-15 7 Indexes CREATE INDEX Statement 7-1 Simple Indexes 7-5 Multi-Key Indexes 7-6 DROP INDEX Statement 7-10 Indexing JSON 7-10 Simple Typed JSON Indexes 7-12 Multi-Key Typed JSON Indexes 7-14 8 Query Optimization Using Indexes for Query Optimization 8-1 Finding Applicable Indexes 8-2 Examples: Using Indexes for Query Optimization 8-2 v Choosing the Best Applicable Index 8-7 9 GeoJson Data Management About GeoJson Data 9-1 Lines and Coordinate System 9-4 Restrictions on GeoJson Data 9-6 Searching for GeoJson Data 9-6 Indexing GeoJson Data 9-12 10 Built-in Functions Functions on Complex Values 10-1 Functions on Sequences 10-1 Functions on Timestamps 10-2 Functions on Rows 10-3 Functions on GeoJson Data 10-3 Functions on Strings 10-5 substring Function 10-5 concat Function 10-7 upper Function 10-8 lower Function 10-9 trim Function 10-10 ltrim Function 10-12 rtrim Function 10-13 length Function 10-14 contains Function 10-15 starts_with Function 10-16 ends_with Function 10-17 index_of Function 10-17 replace Function 10-19 reverse Function 10-21 regex_like Function 10-21 vi 1 Introduction to SQL for Oracle NoSQL Database Structured Query Language (SQL) is the set of statements with which all programs and users access data in the Oracle NoSQL Database. This book provides information on SQL as used by Oracle NoSQL Database. Application programs and Oracle tools often allow users access to the Oracle NoSQL Database without using SQL directly. This chapter contains the following topics: • SQL Program • EBNF Syntax • Comments • Identifiers • Literals • Operator Precedence • Reserved Words Note: No prior knowledge of SQL is required for reading this document. SQL Program The data model of Oracle NoSQL Database supports (a) flat relational data, (b) hierarchical typed (schema-full) data, and (c) schema-less JSON data. SQL for Oracle NoSQL Database is designed to handle all such data in a seamless fashion, without any impedance mismatch among the different sub models. In the current version, an SQL program consists of a single statement, which can be a non-updating query (read-only DML statement), an updating query (updating DML statement), a data definition command (DDL statement), a user management and security statement, or an informational statement. This is illustrated in the following syntax, which lists all the statements supported by the current SQL version. program::= ( query | insert_statement | delete_statement | update_statement | create_namespace_statement | drop_namespace_statement | 1-1 Chapter 1 EBNF Syntax create_table_statement | alter_table_statement | drop_table_statement | create_index_statement | drop_index_statement | create_text_index_statement | create_user_statement | create_role_statement | drop_role_statement | drop_user_statement | alter_user_statement | grant_statement | revoke_statement | describe_statement | show_statement | ) EOF This document is concerned with the first 11 statements in the above list, that is, with read-only queries, insert/delete/update statements, namespace statements, and DDL statements, excluding text indexes. The document describes the syntax and semantics for each statement, and supplies examples. The programmatic APIs available to compile and execute SQL statements and process their results are described in the Getting Started with Oracle NoSQL Database Tables book. EBNF Syntax This specification uses EBNF meta-syntax to specify the grammar of SQL for Oracle NoSQL Database. The following EBNF notations apply: • Upper-case words are used to represent keywords, punctuation characters, operator symbols, and other syntactical entities that are recognized by EBNF as terminals (aka tokens) in the query text. For example, SELECT stands for the "select" keyword in the query text.