Spanner Graph schema overview

Spanner Graph lets you model connected data as a property graph that represents information as a network of nodes and edges. Nodes symbolize entities, and edges show connections between them. Nodes and edges include labels that classify nodes and edges into sets. Nodes and edges also include properties that are key-value pairs.

You define a Spanner Graph schema by mapping rows from input tables to graph nodes and edges. Customize labels and properties for nodes and edges, and understand how schema changes affect graph dependencies. You can also manage schemaless data for more flexible graph definitions.

To learn more about Spanner Graph, see the Spanner Graph overview .

Understand the property graph data model

A property graph lets you model connected data. It represents information as a network of nodes and edges. Nodes symbolize entities in your data landscape, such as customers, products, or locations. Edges show the connections between those nodes, capturing relationships such as purchased, follows, or located-in.

Both nodes and edges can include the following information:

• Labels, which classify nodes and edges into sets, for example, city .
• Properties, which are key-value pairs, for example, population .

The example in Figure 1 shows how you might design a graph to model financial activities. This graph includes the following types of entities modeled as nodes:

• Person:Represents an individual involved in financial transactions.
• Account:Represents a bank account used for transactions.

These entities are connected by different types of relationships, which are represented by the following directed edges:

• Owns:A person owns one or more accounts.
• Transfers:Money moves from one account to another.

Each directed edge indicates a one-way relationship that flows from a source node to a destination node. For example, a Transfers edge connects a source Account to a destination Account , indicating the flow of money.

Figure 1.Example graph with multiple nodes and directed edges.

Nodes and edges include additional information in properties. Each property includes a name and a value.

• Personnodes include these properties:
  • name ( STRING )
  • id ( INT64 )
• Transfersedges include this property:
  • amount (FLOAT64)

Directed and undirected edges

The example graph uses directed edges that indicate a specific direction in the relationship between entities. However, some relationships, like the friend relationship in a social network, are undirected and represent a reciprocal connection without a distinct origin or endpoint. In this case, you can model undirected edges as two directed edges, one edge in each direction.

Spanner Graph schema design

Spanner Graph lets you use the CREATE PROPERTY GRAPH statement to create a graph from tables. The tables that create graphs are called input tables . This approach uses SQL/PGQ (Property Graph Queries) , which is part of SQL:2023 Standards.

Define a node in a property graph

To define a node, add a node definition in the NODE TABLES clause. The simplest form of node definition contains only an input table name. Spanner Graph maps rows from the input table to graph nodes.

In the following example, you use the NODE TABLES clause to define the Account node in the FinGraph property graph. The node definition contains the input table Account .

  -- First, create an Account table. 
 CREATE 
  
 TABLE 
  
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 -- Next, use the Account table as input table of Account node definition. 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 Account 
  
 ); 
 

Default labels and properties

By default, all nodes use the input table name as their label, and Spanner Graph exposes all columns from the input table as node properties.

In the previous example,

• Each account node uses the Account label.
• Each account node includes [id, create_time] properties from the Account table columns.

Element key

A node definition also defines the element key that uniquely identifies a graph node.

• By default, the element key is the primary key of the input table.
• You can use the KEY clause to explicitly define element keys.
• You can use columns with a unique index constraint as element keys.

The following example defines Account node and Person node.

• The Account node uses the Account table's primary key as its element key by default.
• The Person node, on the other hand, explicitly specifies the id as the element key with the KEY clause.

  CREATE 
  
 TABLE 
  
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 name 
  
 STRING 
 ( 
 MAX 
 ), 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 TABLE 
  
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 Person 
  
 KEY 
  
 ( 
 id 
 ), 
  
 Account 
  
 ); 
 

Map a row in the input table to a node in the graph

• Each row with a non-null element key maps to a unique node in the graph, identified by the element key.
• Rows with a null element key are ignored.

Define an edge in a property graph

To define an edge, add an edge definition into the EDGE TABLES clause. The simplest form of edge definition contains only an input table name. Spanner Graph maps rows from the input table to graph edges.

• The default label and properties of the edges are defined in the same way as nodes .

• Each edge's element key is defined in the same way as nodes .

Source and destination node references

In the following example, you create a property graph FinGraph with the following:

• Person and Account nodes
• PersonOwnAccount edge

  CREATE 
  
 TABLE 
  
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 name 
  
 STRING 
 ( 
 MAX 
 ), 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 TABLE 
  
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 TABLE 
  
 PersonOwnAccount 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 account_id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 FOREIGN 
  
 KEY 
  
 ( 
 account_id 
 ) 
  
 REFERENCES 
  
 Account 
  
 ( 
 id 
 ) 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 , 
  
 account_id 
 ), 
  
 INTERLEAVE 
  
 IN 
  
 PARENT 
  
 Person 
 ; 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 Person 
 , 
  
 Account 
  
 ) 
  
 EDGE 
  
 TABLES 
  
 ( 
  
 PersonOwnAccount 
  
 SOURCE 
  
 KEY 
  
 ( 
 id 
 ) 
  
 REFERENCES 
  
 Person 
  
 ( 
 id 
 ) 
  
 DESTINATION 
  
 KEY 
  
 ( 
 account_id 
 ) 
  
 REFERENCES 
  
 Account 
  
 ( 
 id 
 ) 
  
 ); 
 

An edge definition defines the source and destination node reference by using the SOURCE KEY , DESTINATION KEY , and REFERENCES clauses. The following example uses the edge definition of PersonOwnAccount to illustrate this concept:

  EDGE 
  
 TABLES 
  
 ( 
  
 PersonOwnAccount 
  
 SOURCE 
  
 KEY 
  
 ( 
 id 
 ) 
  
 REFERENCES 
  
 Person 
  
 ( 
 id 
 ) 
  
 DESTINATION 
  
 KEY 
  
 ( 
 account_id 
 ) 
  
 REFERENCES 
  
 Account 
  
 ( 
 id 
 ) 
 ) 
 

Each PersonOwnAccount edge connects a Person (source) to an Account (destination) node.

• The source node of an edge is a Person node where the id is the same as the edge id .
• The destination node of an edge is an Account node where the id is the same as the edge account_id .

Additionally, the following is true for the PersonOwnAccount edge:

• The element key is the primary key of the PersonOwnAccount table, namely (id, account_id) .
• Each edge has the same set of properties as the columns from the PersonOwnAccount table.
• Each edge has the default PersonOwnAccount label.

Map a row in an edge input table to edges in the graph

• Each row in the edge input table, where the element key is not null, usually maps to a unique edge in your graph.
• A row might correspond to zero or more than one edge in the graph. For example, this occurs when the source node reference matches zero or more nodes in the source node table.
• You can use the same input table in different node or edge definitions to create different sets of nodes or edges. For more information, see Merge node and edge input tables .

Customize labels and properties

You can use the LABEL and PROPERTIES clauses to customize labels and properties.

The following example defines two nodes: Person and Account .

• The Person nodes use the Customer label to expose the address property. The address property is defined by the expression CONCAT(city, ", ", country), that refers to the city and country column from the input table Person .
• For Account , the Account node uses the Account label to expose the id and create_time properties.
• Person and Account have the Entity label with properties [ id, name ].
  • For Person , the id and name properties come from the input table columns.
  • For Account , the name property refers to the nick_name column of the input table.

  CREATE 
  
 TABLE 
  
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 name 
  
 STRING 
 ( 
 MAX 
 ), 
  
 birthday 
  
 TIMESTAMP 
 , 
  
 country 
  
 STRING 
 ( 
 MAX 
 ), 
  
 city 
  
 STRING 
 ( 
 MAX 
 ), 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 TABLE 
  
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 is_blocked 
  
 BOOL 
 , 
  
 nick_name 
  
 STRING 
 ( 
 MAX 
 ), 
 ) 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ); 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 Person 
  
 KEY 
  
 ( 
 id 
 ) 
  
 LABEL 
  
 Customer 
  
 PROPERTIES 
  
 ( 
 CONCAT 
 ( 
 city 
 , 
  
 ", " 
 , 
  
 country 
 ) 
  
 AS 
  
 address 
 ) 
  
 LABEL 
  
 Entity 
  
 PROPERTIES 
  
 ( 
 id 
 , 
  
 name 
 ), 
  
 Account 
  
 KEY 
  
 ( 
 id 
 ) 
  
 LABEL 
  
 Account 
  
 PROPERTIES 
  
 ( 
 id 
 , 
  
 create_time 
 ) 
  
 LABEL 
  
 Entity 
  
 PROPERTIES 
  
 ( 
 id 
 , 
  
 nick_name 
  
 AS 
  
 name 
 ) 
  
 ); 
 

Label and property consistency

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

• Properties with the same name use the same value type.
• Labels with the same name expose the same list of properties.

In the previous example, the Entity label is defined in both Person and Account nodes. Both definitions include the same set of property names [ id , name ] with identical value types.

Dependencies between graphs and other schema objects

The graph created by CREATE PROPERTY GRAPH depends on other schema objects, such as the input tables of the node and edge definitions, and the table columns referenced by the properties. Spanner Graph doesn't permit a schema change that breaks one of these dependencies.

The following statement makes FinGraph dependent on the Account table and the id and create_time columns.

  CREATE 
  
 OR 
  
 REPLACE 
  
 PROPERTY 
  
 GRAPH 
  
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 Account 
  
 PROPERTIES 
  
 ( 
 id 
 , 
  
 create_time 
 ) 
  
 ); 
 

In this example, Spanner Graph doesn't permit the following schema changes:

• You can't drop the Account table. To do this, you need to remove the Account node definition. For more information, see Remove existing nodes or edge definitions .
• You can't drop create_time columns from the Account table. To do this, you need to remove the create_time property from the Account node definition. For more information, see Update existing nodes or edges definitions .

However, you can make the following schema changes:

• Modify the Account table and id and create_time columns schema if other schema requirements permit it. For more information, see Make schema updates .

View a schema visualization

You can view a schema visualization in Spanner Studio after you run a Spanner Graph query. For more information, see Work with Spanner Graph visualizations .

Manage schemaless data

Spanner Graph also supports schemaless data management that is helpful when you need a more flexible graph definition. For more information, see Manage schemaless data in Spanner Graph .

What's next

• Create a Spanner Graph schema .
• Update or delete a Spanner Graph schema .
• Manage schemaless data with Spanner Graph .