Note: This feature is available with the Spanner Enterprise edition and Enterprise Plus edition. For more information, see theSpanner editions overview.

Spanner Graph lets you model connected data as a property graph thatrepresents information as a network of nodes and edges. Nodes symbolizeentities, and edges show connections between them. Nodes and edges includelabels that classify the types of nodes and edges. Nodes and edges also includeproperties that describe them.

This document describes how to define a Spanner Graph schema bymapping rows of tables to graph nodes and edges. You also learnhow to customize labels and properties for nodes and edgesandhow to work with graph and schema object dependencies.

If you want more flexible graph definitions, seeManage schemaless data. If youwant to learn about using SQL views instead of tables to define nodes and edges,seeOverview of graphs created from SQL views.To learn more about Spanner Graph, see theSpanner Graph overview.

Understand the property graph data model

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

Both nodes and edges can include the following information:

• Labels: Classify nodes and edge types. If you don't explicitly define alabel for a node or an edge, Spanner Graph uses the input tablename as the default label. For example,Account could be a label.

• Properties: Used to describe nodes and edges. For example, aPersonnode might have aname property with the valueAlex and anid propertywith the value1.

The example in Figure 1 shows how you might design a graph to model financialactivities. 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 arerepresented 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 sourcenode to a destination node. For example, aTransfers edge connects a sourceAccount to a destinationAccount, indicating the flow of money.

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

Nodes and edges include additional information in properties.

• Person nodes include these properties:
  • name (STRING)
  • id (INT64)
• Transfers edges include this property:
  • amount (FLOAT64)

Directed and undirected edges

The example graph usesdirected edges that indicate a specific direction inthe relationship between entities. However, some relationships, like thefriend relationship in a social network, are undirected and represent areciprocal connection without a distinct origin or endpoint. In this case, youcan model undirected edges as two directed edges, one edge in each direction.

Spanner Graph schema design

In Spanner Graph you use theCREATE PROPERTY GRAPHstatement to create a graph from tables or SQL views. The tables that are usedto create graphs are calledinput tables. This document shows you how to usetables to create a graph. For information about using SQL views, seeCreate a Spanner Graph from a SQL view.

Define a node from a table

To define a node, add a node definition in theNODE TABLESclause. The simplest form of a node definition contains the name of an inputtable that has defined source and destination node references.Spanner Graph maps rows from the input table to graph nodes.

In the following example, you use theNODE TABLESclause to define theAccount node in theFinGraph property graph. The nodedefinition contains the input tableAccount.

-- First, create an Account table.CREATETABLEAccount(idINT64NOTNULL,create_timeTIMESTAMP,)PRIMARYKEY(id);-- Next, use the Account table as input table of Account node definition.CREATEPROPERTYGRAPHFinGraphNODETABLES(Account);

Default labels and properties

In addition to using the input table name as the default label,Spanner Graph exposes all columns from the input table as nodeproperties.

In the previous example,

• Each account node uses theAccount label.
• Each account node includes[id, create_time] properties from theAccounttable columns.

Element key

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

• By default, the element key is the primary key of the input table.
• You can use theKEY clause to explicitly define element keys.
• You can use columns with aunique index constraintas element keys.

The following example definesAccount node andPerson node.

• TheAccount node uses theAccount table's primary key as its element keyby default.
• ThePerson node, on the other hand, explicitly specifies theid as theelement key with theKEY clause.

CREATETABLEPerson(idINT64NOTNULL,nameSTRING(MAX),)PRIMARYKEY(id);CREATETABLEAccount(idINT64NOTNULL,create_timeTIMESTAMP,)PRIMARYKEY(id);CREATEPROPERTYGRAPHFinGraphNODETABLES(PersonKEY(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.

To define an edge, add an edge definition into theEDGE TABLESclause. 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 aredefined in the same way as nodes.

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

Source and destination node references

In the following example, you create a property graphFinGraph with thefollowing:

• Person andAccount nodes
• PersonOwnAccount edge

CREATETABLEPerson(idINT64NOTNULL,nameSTRING(MAX),)PRIMARYKEY(id);CREATETABLEAccount(idINT64NOTNULL,create_timeTIMESTAMP,)PRIMARYKEY(id);CREATETABLEPersonOwnAccount(idINT64NOTNULL,account_idINT64NOTNULL,create_timeTIMESTAMP,FOREIGNKEY(account_id)REFERENCESAccount(id))PRIMARYKEY(id,account_id),INTERLEAVEINPARENTPerson;CREATEPROPERTYGRAPHFinGraphNODETABLES(Person,Account)EDGETABLES(PersonOwnAccountSOURCEKEY(id)REFERENCESPerson(id)DESTINATIONKEY(account_id)REFERENCESAccount(id));

An edge definition defines the source and destination node reference by usingtheSOURCE KEY,DESTINATION KEY, andREFERENCES clauses. The followingexample uses the edge definition ofPersonOwnAccount to illustrate thisconcept:

EDGETABLES(PersonOwnAccountSOURCEKEY(id)REFERENCESPerson(id)DESTINATIONKEY(account_id)REFERENCESAccount(id))

EachPersonOwnAccount edge connects aPerson (source) to anAccount(destination) node.

• The source node of an edge is aPerson node where theid is the same asthe edgeid.
• The destination node of an edge is anAccount node where theid is thesame as the edgeaccount_id.

• Each row in the edge input table, where the element key is not null, usuallymaps to a unique edge in your graph.
• A row might correspond to zero or more than one edge in the graph. Forexample, this occurs when thesource node reference matches zero ormore nodes in the source node table.

Define nodes and edges within a single table

You can define a node and its incoming or outgoing edges in a single table ifyour table's columns define a relationship to another table. This approachreduces the number of tables, simplifies data management, and can improve queryperformance by eliminating the need for a join to a separate edge table.

For example, if the followingAccount table has a composite primary key(owner_id, account_id), theowner_id part can be a foreign key thatreferences aPerson table. This structure allows theAccount table torepresent both theAccount node and the incoming edge from thePerson node.

CREATETABLEPerson(idINT64NOTNULL,)PRIMARYKEY(id);-- Assume each account has exactly one owner.CREATETABLEAccount(owner_idINT64NOTNULL,account_idINT64NOTNULL,FOREIGNKEY(owner_id)REFERENCESPerson(id))PRIMARYKEY(owner_id,account_id);

You can use theAccount table to define both theAccount node and itsincomingOwns edge. This is shown in the followingCREATE PROPERTY GRAPHstatement. In theEDGE TABLES clause, you give theAccount table the aliasOwns. This is because each element in the graph schema must have a uniquename.

CREATEPROPERTYGRAPHFinGraphNODETABLES(Person,Account)EDGETABLES(AccountASOwnsSOURCEKEY(owner_id)REFERENCESPersonDESTINATIONKEY(owner_id,account_id)REFERENCESAccount);

Customize labels and properties

You can use theLABELandPROPERTIESclauses to customize labels and properties.

The following example defines two nodes:Person andAccount.

• ThePerson nodes use theCustomer label to expose theaddressproperty. Theaddress property is defined by the expressionCONCAT(city,", ", country), that refers to thecity andcountry column from theinput tablePerson.
• ForAccount, theAccount node uses theAccount label to expose theid andcreate_time properties.
• Person andAccount have theEntity label with properties [id, name].
  • ForPerson, theid andname properties come from the input tablecolumns.
  • ForAccount, thename property refers to thenick_name column ofthe input table.

CREATETABLEPerson(idINT64NOTNULL,nameSTRING(MAX),birthdayTIMESTAMP,countrySTRING(MAX),citySTRING(MAX),)PRIMARYKEY(id);CREATETABLEAccount(idINT64NOTNULL,create_timeTIMESTAMP,is_blockedBOOL,nick_nameSTRING(MAX),)PRIMARYKEY(id);CREATEPROPERTYGRAPHFinGraphNODETABLES(PersonKEY(id)LABELCustomerPROPERTIES(CONCAT(city,", ",country)ASaddress)LABELEntityPROPERTIES(id,name),AccountKEY(id)LABELAccountPROPERTIES(id,create_time)LABELEntityPROPERTIES(id,nick_nameASname));

Label and property consistency

In a graph, labels and properties are uniquely identified by their names. Youcan use labels and properties with the same name in multiple node or edgedefinitions. However, labels and properties with the same name must follow theserules:

• 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, theEntity label is defined in bothPerson andAccount 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 byCREATE PROPERTY GRAPH depends on other schema objects,such as the input tables of the node and edge definitions, and the table columnsreferenced by the properties. Spanner Graph doesn't permit a schemachange that breaks one of these dependencies.

The following statement makesFinGraph dependent on theAccount table andtheid andcreate_time columns.

CREATEORREPLACEPROPERTYGRAPHFinGraphNODETABLES(AccountPROPERTIES(id,create_time));

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

• You can't drop theAccount table. To do this, you need to remove theAccount node definition. For more information, seeRemove existing nodes or edge definitions.
• You can't dropcreate_time columns from theAccount table. To do this,you need to remove thecreate_time property from theAccount nodedefinition. For more information, seeUpdate existing nodes or edges definitions.

However, you can make the following schema changes:

• Modify theAccount table andid andcreate_time columns schema ifother schema requirements permit it. For more information, seeMake schema updates.

View a schema visualization

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

Manage schemaless data

Spanner Graph also supports schemaless data management that is helpfulwhen you need a more flexible graph definition. For more information, seeManage 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.