docs/_docs/sql-reference/grammar-reference.adoc

// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Grammar Reference

This section describes grammar elements that are common to multiple SQL functions (link:sql-reference/ddl[DDL], link:sql-reference/distribution-zones[Distribution Zones], etc.).

== column_definition_or_list

[.diagram-container]
Diagram(
Choice(0,
Sequence(
Choice(0,
Sequence(
Choice(0,Sequence(
NonTerminal('column_name'),
NonTerminal('data_type'))
)),
Sequence(
Terminal('('),
OneOrMore(Sequence(
NonTerminal('column_name'),
NonTerminal('data_type')),
Terminal(',')
),Terminal(')')
)))))

Keywords and parameters:

* `column_name` - a column name.
* `data_type` - a valid link:sql-reference/data-types[data type].


Referenced by:

* link:sql-reference/ddl#alter-table[ALTER TABLE]

'''

== column_name_or_list

[.diagram-container]
Diagram(
Choice(0,
Sequence(
Choice(0,
Sequence(
Choice(0,Sequence(
NonTerminal('column_name'))
)),
Sequence(
Terminal('('),
OneOrMore(Sequence(
NonTerminal('column_name')),
Terminal(',')
),Terminal(')')
)))))


Keywords and parameters:

* `column_name` - a column name.


Referenced by:

* link:sql-reference/ddl#create-table[CREATE TABLE]
* link:sql-reference/ddl#alter-table[ALTER TABLE]
* link:sql-reference/ddl#create-index[CREATE INDEX]
* <<constraint>>


'''

== sorted_column_list

[.diagram-container]
Diagram(
Sequence('(', OneOrMore(Sequence(NonTerminal('column_name'), Optional(Choice(0, Terminal('ASC'), Terminal('DESC')))), ','), ')')
)

Keywords and parameters:

* `column_name` - a column name.


Referenced by:

* link:sql-reference/ddl#create-index[CREATE INDEX]
* <<constraint>>

'''

== constraint

[.diagram-container]
Diagram(Sequence(
Optional(Sequence(Terminal('CONSTRAINT'),NonTerminal('constraint_name')
)),
Terminal('PRIMARY KEY'),
Optional(
Choice(0,
Sequence(
Terminal('USING'),
Choice (0,
Sequence(Terminal('SORTED'), NonTerminal('sorted_column_list', {href:'./grammar-reference/#sorted_column_list'})
),
Sequence('HASH', NonTerminal('column_list', {href:'./grammar-reference/#column_list'})))
))
)))

Keywords and parameters:

* `constraint_name` - a name of the constraint.

Referenced by:

* link:sql-reference/ddl#create-table[CREATE TABLE]

'''

== qualified_table_name

[.diagram-container]
Diagram(Sequence(
Optional(Sequence(NonTerminal('schema'),NonTerminal('.')
),),
NonTerminal('table_name')
),
)

Keywords and parameters:

* `schema` - a name of the table schema.
* `table_name` - a name of the table.

Referenced by:

* link:sql-reference/ddl#create-table[CREATE TABLE]
* link:sql-reference/ddl#alter-table[ALTER TABLE]
* link:sql-reference/ddl#drop-table[DROP TABLE]
* link:sql-reference/ddl#create-index[CREATE INDEX]

'''

== column_definition

[.diagram-container]
Diagram(
Sequence(
NonTerminal('column_name'),
NonTerminal('DATA TYPE', {href:'./data-types'}),
Optional(Sequence(Optional('NOT'),Terminal('NULL')))
),
End({type:'complex'})
)

[.diagram-container]
Diagram(
Start({type:'complex'}),
Sequence(
Optional(Sequence(Terminal('DEFAULT'), Choice(1,NonTerminal('identifier'),
NonTerminal('literal_value'),
Sequence(Terminal('CURRENT TIMESTAMP'), Optional(Sequence(Terminal('+'),Terminal('INTERVAL'), NonTerminal('interval')))
)
),)),
Optional(Terminal('PRIMARY KEY')),
))

Keywords and parameters:

* `column_name` - a column name.
* `DATA TYPE` - the link:sql-reference/data-types[data type] allowed in the column.
* `identifier` - the random identifier for the row. Can be generated by using the <<rand_uuid>> function.
* `literal_value` - a value to be assigned as default.
* `CURRENT TIMESTAMP` - the function that returns current time. Can only be used for `TIMESTAMP` columns.
* `interval` - the time interval by which the timestamp should be offset.

Referenced by:

* link:sql-reference/ddl#сreate-table[CREATE TABLE]
* link:sql-reference/ddl#alter-table[ALTER TABLE]
* link:sql-reference/ddl#create-index[CREATE INDEX]
* link:sql-reference/distribution-zones#create-zone[CREATE ZONE]

'''

== parameter

[.diagram-container]
Diagram(
  NonTerminal('parameter_name'),
  Terminal('='),
  NonTerminal('parameter_value'))

Parameters:

* `parameter_name` - the name of the parameter.
* `parameter_value` - the value of the parameter.

When a parameter is specified, you can provide it as a literal value or as an identifier. For example:

----
CREATE ZONE test_zone;
CREATE TABLE test_table (id INT PRIMARY KEY, val INT) WITH PRIMARY_ZONE=test_zone;
----

In this case, `test_zone` is the identifier, and is used as an identifier. When used like this, the parameters are not case-sensitive.

----
CREATE ZONE "test_zone";
CREATE TABLE test_table (id INT PRIMARY KEY, val INT) WITH PRIMARY_ZONE='test_zone';
----

In this case, `test_zone` is created as a literal value, and is used as a literal. When used like this, the parameter is case-sensitive.

----
CREATE ZONE test_zone;
CREATE TABLE test_table (id INT PRIMARY KEY, val INT) WITH PRIMARY_ZONE=`TEST_ZONE`;
----

In this case, `test_zone` is created as an identifier, and is case-insensitive. As such, when `TEST_ZONE` is used as a literal, it still matches the identifier.


Referenced by:

* link:sql-reference/ddl#сreate-table[CREATE TABLE]
* link:sql-reference/distribution-zones#create-zone[CREATE ZONE]
* link:sql-reference/distribution-zones#alter-zone[ALTER ZONE]

'''

== System Functions

=== rand_uuid

This function generates a random UUID value each time it is called.

Example:

[source,sql]
----
CREATE TABLE t (id uuid default rand_uuid primary key, val int)
----

Referenced by:

* link:sql-reference/ddl#create-table[CREATE TABLE]