GQL schema statements

Graph Query Language (GQL) supports all GoogleSQL schema statements, including the following GQL-specific schema statements:

Statement list

Name	Summary
`CREATE PROPERTY GRAPH` statement	Creates a property graph.
`DROP PROPERTY GRAPH` statement	Deletes a property graph.

`CREATE PROPERTY GRAPH` statement

Property graph definition

CREATE
  [ OR REPLACE ]
  PROPERTY GRAPH
  [ IF NOT EXISTS ]
  property_graph_name
  property_graph_content;

property_graph_content:
  node_tables
  [ edge_tables ]

node_tables:
  NODE TABLES element_list

edge_tables:
  EDGE TABLES element_list

element_list:
  (element[, ...])

Description

Creates a property graph.

Definitions

OR REPLACE: Replaces any property graph with the same name if it exists. If the property graph does not exist, creates the property graph. Can't appear with IF NOT EXISTS.
IF NOT EXISTS: If any property graph exists with the same name, the CREATE statement has no effect. Can't appear with OR REPLACE.
OPTIONS: If you have schema options, you can add them when you create the property graph. These options are system-specific and follow the Spanner HINT syntax
property_graph_name: The name of the property graph. This name can be a path expression. This name must not conflict with the name of an existing table, view, or property graph.
property_graph_content: Add the definitions for the nodes and edges in the property graph.

node_tables: A collection of node definitions. A node definition defines a new type of node in the graph.

The following example represents three node definitions: Account, Customer, and GeoLocation.

NODE TABLES (
  Account,
  Customer
    LABEL Client
    PROPERTIES (cid, name),
  Location AS GeoLocation
    DEFAULT LABEL
    PROPERTIES ALL COLUMNS
)

edge_tables: A collection of edge definitions. An edge definition defines a new type of edge in the graph. An edge is directed and connects a source and a destination node.

The following example represents two edge definitions: Own and Transfer.

EDGE TABLES (
  Own
    SOURCE KEY (cid) REFERENCES Customer (cid)
    DESTINATION KEY (aid) REFERENCES Account
    NO PROPERTIES,
  Transfer
    SOURCE KEY (from_id) REFERENCES Account (aid)
    DESTINATION KEY (to_id) REFERENCES Account (aid)
    LABEL Transfer NO PROPERTIES
)

element_list: A list of element (node or edge) definitions.
element: Refer to Element definition for details.

Element definition

element:
  element_name
  [ AS element_alias ]
  [ element_keys ]
  [ { label_and_properties_list | element_properties } ]

element_keys:
  { node_element_key | edge_element_keys }

node_element_key:
  element_key

edge_element_keys:
  element_key
  source_key
  destination_key

element_key:
  KEY column_name_list

source_key:
  SOURCE KEY column_name_list
  REFERENCES element_alias_reference [ column_name_list ]

destination_key:
  DESTINATION KEY column_name_list
  REFERENCES element_alias_reference [ column_name_list ]

column_name_list:
  (column_name[, ...])

Description

Adds an element definition to the property graph. For example:

Customer
  LABEL Client
    PROPERTIES (cid, name)

In a graph, labels and properties are uniquely identified by their names. Labels and properties with the same name can appear in multiple node or edge definitions. However, labels and properties with the same name must follow these rules:

Properties with the same name must have the same value type.
Labels with the same name must expose the same set of properties.

Definitions

element_name: The name of the input table from which elements are created.
element_alias: An optional alias. You must use an alias if you use an input table for more than one element definition.
element_keys: The key for a graph element. This uniquely identifies a graph element.
- By default, the element key is the primary key of the input table.
- Element keys can be explicitly defined with the KEY clause.
- Columns with uniqueness constraints can be used as element keys.
node_element_key: The element key for a node.
```
KEY (item1_column, item2_column)
```

edge_element_keys: The element key, source key, and destination key for an edge.

KEY (item1_column, item2_column)
SOURCE KEY (item1_column) REFERENCES item_node (item_node_column)
DESTINATION KEY (item2_column) REFERENCES item_node (item_node_column)

element_key: The key that identifies the node or edge element.
```
KEY (item1_column, item2_column)
```

source_key: The key for the source node of the edge.

SOURCE KEY (item1_column) REFERENCES item_node (item_node_column)

destination_key: The key for the destination node of the edge.

DESTINATION KEY (item2_column) REFERENCES item_node (item_node_column)

column_name_list: One or more columns to assign to a key.

In column_name_list, column names must be unique.

If column_name_list is used in REFERENCES of source_key or destination_key, the columns they reference must exist in the corresponding node tables.

If column_name_list is absent in REFERENCES of source_key or destination_key, a foreign key constraint must exist on the edge table's SOURCE KEY columns or DESTINATION KEY columns to their corresponding node tables.
element_alias_reference: The alias of another element to reference.
label_and_property_list: The list of labels and properties to add to an element. For more information, see Label and properties list definition.

Label and properties list definition

label_and_properties_list:
  label_and_properties[...]

label_and_properties:
  element_label
  [ element_properties ]

element_label:
  {
    LABEL label_name |
    DEFAULT LABEL
  }

Description

Adds a list of labels and properties to an element.

Definitions

label_and_properties: The label to add to the element and the properties exposed by that label. For example:
```
LABEL Tourist
  PROPERTIES ARE ALL COLUMNS EXCEPT (home_city, home_country)
```
When label_and_properties is not specified, the following is applied implicitly:
```
DEFAULT LABEL PROPERTIES ARE ALL COLUMNS
```
A property must be unique in label_and_properties.
element_label: Add a custom label or use the default label for the element. label_name must be unique in element.

If you use DEFAULT LABEL, label_name is the same as element_table_alias.
element_properties: The properties associated with a label. A property can't be used more than once for a specific label. For more information, see Element properties definition.

Element properties definition

element_properties:
  {
    NO PROPERTIES |
    properties_are |
    derived_property_list
  }

properties_are:
  PROPERTIES [ ARE ] ALL COLUMNS [ EXCEPT column_name_list ]

column_name_list:
  (column_name[, ...])

derived_property_list:
  PROPERTIES derived_property[, ...]

derived_property:
  value_expression [ AS property_name ]

Description

Adds properties associated with a label.

Definitions

NO PROPERTIES: The element doesn't have properties.
properties_are: Define which columns to include as element properties.

If you don't include this definition, all columns are included by default, and the following definition is applied implicitly:
```
PROPERTIES ARE ALL COLUMNS
```
In the following examples, all columns in a table are included as element properties:
```
PROPERTIES ARE ALL COLUMNS
```
```
PROPERTIES ALL COLUMNS
```
In the following example, all columns in a table except for home_city and home_country are included as element properties:
```
PROPERTIES ARE ALL COLUMNS EXCEPT (home_city, home_country)
```
column_name_list: A list of columns to exclude as element properties.

Column names in the EXCEPT column_name_list must be unique.
derived_property_list: A list of element property definitions.
derived_property: An expression that defines a property and can optionally reference the input table columns.

In the following example, the id and name columns are included as properties. Additionally, the result of the salary + bonus expression are included as the income property:
```
PROPERTIES (id, name, salary + bonus AS income)
```
A derived property includes:
- value_expression: An expression that can be represented by simple constructs such as column references and functions. Subqueries are excluded.
- AS property_name: Alias to assign to the value expression. This is optional unless value_expression is a function.
If derived_property has any column reference in value_expression, that column reference must refer to a column of the underlying table.

If derived_property doesn't define property_name, value_expression must be a column reference and the implicit property_name is the column name.

`FinGraph` Example

The following property graph, FinGraph, contains two node definitions (Account and Person) and two edge definitions (PersonOwnAccount and AccountTransferAccount).

CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Account,
    Person
  )
  EDGE TABLES (
    PersonOwnAccount
      SOURCE KEY (id) REFERENCES Person (id)
      DESTINATION KEY (account_id) REFERENCES Account (id)
      LABEL Owns,
    AccountTransferAccount
      SOURCE KEY (id) REFERENCES Account (id)
      DESTINATION KEY (to_id) REFERENCES Account (id)
      LABEL Transfers
  );

Once the property graph is created, you can use it in GQL queries. For example, the following query matches all nodes labeled Person and then returns the name values in the results.

GRAPH FinGraph
MATCH (p:Person)
RETURN p.name

/*---------+
 | name    |
 +---------+
 | Alex    |
 | Dana    |
 | Lee     |
 +---------*/

`DROP PROPERTY GRAPH` statement

DROP PROPERTY GRAPH [ IF EXISTS ] property_graph_name;

Description

Deletes a property graph.

Definitions

IF EXISTS: If a property graph of the specified name doesn't exist, then the DROP statement has no effect and no error is generated.
property_graph_name: The name of the property graph to drop.

Example

DROP PROPERTY GRAPH FinGraph;

`INFORMATION SCHEMA`

Use the SQL INFORMATION_SCHEMA to look up schemas created by the CREATE PROPERTY GRAPH statement.

GQL schema statements

Statement list

CREATE PROPERTY GRAPH statement

Property graph definition

Element definition

Label and properties list definition

Element properties definition

FinGraph Example

DROP PROPERTY GRAPH statement

INFORMATION SCHEMA

`CREATE PROPERTY GRAPH` statement

`FinGraph` Example

`DROP PROPERTY GRAPH` statement

`INFORMATION SCHEMA`