Console
    Start free

    Schema overview

    This document explains the components of a property graph schema and shows you how to create and manage a graph schema.

    Graphs let you model connected data that represents information as a network of nodes and edges. A graph schema consists of nodes and edges, along with labels that classify type their type, and properties that describe them. You define a property graph schema by mapping rows from input tables to graph nodes and edges and defining custom labels and properties. To learn more about BigQuery Graph, see the BigQuery Graph overview .

    Understand the property graph data model

    A property graph lets you model connected data as a network of nodes and edges. Nodes represent entities in your data, such as customers, products, or locations. Edges represent connections between those nodes, capturing relationships such as purchases, follows, or locations.

    Nodes and edges can include the following information:

    • Labels: classify nodes and edge types. For example, students in a class might have a Student label and a Person label. If you don't explicitly define a label for a node or an edge, BigQuery Graph uses the input table name as the default label.

    • Properties: used to describe nodes and edges. For example, a node that represents a person might have a name property with the value Alex and an id property with the value 1 .

    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.

    Nodes, edges, labels, and properties of a financial graph.

    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

    Directed edges indicate a specific direction in the relationship between entities. For example, a person owns an account, but an account doesn't own a person. However, some relationships, like the friend relationship in a social network, are undirected and represent a reciprocal connection. In this case, you can model undirected edges as two directed edges, one edge in each direction.

    Design your schema

    BigQuery Graph lets you use the CREATE PROPERTY GRAPH statement to create a graph from tables. The tables that create graphs are called input tables .

    Define a node

    Nodes are defined by rows in tables. To define a node, add a node definition in the NODE TABLES clause . The simplest form of a node definition contains the name of an input table with a primary key . BigQuery 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 .

      -- Create an Account table. 
 CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 -- Use the Account table as the input table for the Account node definition. 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 graph_db 
 . 
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 graph_db 
 . 
 Account 
  
 );

    By default, BigQuery uses the table name as the label and exposes all columns from the input table as properties.

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

    Element key

    A node definition also defines the element key , a collection of columns that uniquely identifies a graph node. By default, the element key is the primary key of the input table. Alternatively, you can use the KEY clause to explicitly define element keys.

    The following example defines an Account node and a Person node. The Account node uses the Account table's primary key as its element key. The Person node explicitly specifies the id column as the element key by using the KEY clause.

      CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 name 
  
 STRING 
 ); 
 CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 graph_db 
 . 
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 graph_db 
 . 
 Person 
  
 KEY 
  
 ( 
 id 
 ), 
  
 graph_db 
 . 
 Account 
  
 );
    • 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.

    The same input table can be used in multiple node definitions. In this case, a given row in the input table maps to one node for each node definition.

    Define an edge

    Edges are defined by rows in tables. To define an edge, add an edge definition to the EDGE TABLES clause . The simplest form of edge definition contains the name of an input table and defines source and destination node references. BigQuery Graph uses this definition to map rows from the input table to graph edges.

    By default, BigQuery uses the table name as the label and exposes all columns from the input table as properties.

    Source and destination node references

    An edge definition defines the source and destination node reference by using the SOURCE KEY , DESTINATION KEY , and REFERENCES clauses. You must define the source and destination nodes before using them in the edge definition.

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

    • Person and Account nodes
    • PersonOwnAccount edge
      CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 name 
  
 STRING 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Account 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 CREATE 
  
 TABLE 
  
 graph_db 
 . 
 PersonOwnAccount 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 account_id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 create_time 
  
 TIMESTAMP 
 , 
  
 FOREIGN 
  
 KEY 
  
 ( 
 account_id 
 ) 
  
 REFERENCES 
  
 graph_db 
 . 
 Account 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 , 
  
 account_id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 graph_db 
 . 
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 graph_db 
 . 
 Person 
 , 
  
 graph_db 
 . 
 Account 
  
 ) 
  
 EDGE 
  
 TABLES 
  
 ( 
  
 PersonOwnAccount 
  
 SOURCE 
  
 KEY 
  
 ( 
 id 
 ) 
  
 REFERENCES 
  
 Person 
  
 ( 
 id 
 ) 
  
 DESTINATION 
  
 KEY 
  
 ( 
 account_id 
 ) 
  
 REFERENCES 
  
 Account 
  
 ( 
 id 
 ) 
  
 );

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

    • The source node of an edge is a Person node where the id property is the same as the edge id property.
    • The destination node of an edge is an Account node where the id property is the same as the edge account_id property.
    • 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 rows to edges

    Each row in the edge input table with a non-null element key typically maps to a single edge in your graph. However, if the source or destination node reference matches zero or more nodes in the source or destination node table, then the row in the edge input table could result in zero or multiple edges in your graph.

    Define nodes and edges within a single table

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

    For example, if the following Account table has a composite primary key (owner_id, account_id) , the owner_id column can be a foreign key that references a Person table. This structure allows the Account table to represent both the Account node and the incoming edge from the Person node.

      CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Person 
  
 ( 
  
 id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 ); 
 -- Assume each account has exactly one owner. 
 CREATE 
  
 TABLE 
  
 graph_db 
 . 
 Account 
  
 ( 
  
 owner_id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 account_id 
  
 INT64 
  
 NOT 
  
 NULL 
 , 
  
 FOREIGN 
  
 KEY 
  
 ( 
 owner_id 
 ) 
  
 REFERENCES 
  
 graph_db 
 . 
 Person 
 ( 
 id 
 ) 
  
 NOT 
  
 ENFORCED 
 , 
  
 PRIMARY 
  
 KEY 
  
 ( 
 owner_id 
 , 
  
 account_id 
 ) 
  
 NOT 
  
 ENFORCED 
 );

    You can use the Account table to define both the Account node and its incoming Owns edge. This is shown in the following CREATE PROPERTY GRAPH statement. In the EDGE TABLES clause, you give the Account table the alias Owns . This is because each element in the graph schema must have a unique name.

      CREATE 
  
 PROPERTY 
  
 GRAPH 
  
 graph_db 
 . 
 FinGraph 
  
 NODE 
  
 TABLES 
  
 ( 
  
 graph_db 
 . 
 Person 
 , 
  
 graph_db 
 . 
 Account 
  
 ) 
  
 EDGE 
  
 TABLES 
  
 ( 
  
 graph_db 
 . 
 Account 
  
 AS 
  
 Owns 
  
 SOURCE 
  
 KEY 
  
 ( 
 owner_id 
 ) 
  
 REFERENCES 
  
 Person 
  
 DESTINATION 
  
 KEY 
  
 ( 
 owner_id 
 , 
  
 account_id 
 ) 
  
 REFERENCES 
  
 Account 
  
 );

    Customize labels and properties

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

    The following example defines a Person node with a custom property and an Account node with multiple labels:

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

    • 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 .

    • The Account node uses the Account label to expose the id and create_time properties.

    The Person and Account nodes both have the Entity label with properties id and name .

    • In the Person node, the id and name properties come from the input table columns.
    • In the Account node, the name property refers to the nick_name column of the input table.

    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 must use the same value type.
    • Labels with the same name must expose the same list of properties.

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

    Manage schema dependencies

    Graphs depend on the schema of the input tables to the node and edge definitions, and the table columns referenced by the properties. BigQuery Graph doesn't check whether deleting or altering tables or columns invalidates an existing graph schema.

    You are responsible for avoiding breaking schema changes. Follow these best practices:

    • Before you delete a table used in a graph node definition, first remove that node definition from the graph.
    • Before you remove a column from a table that is exposed as a property in a graph, remove the property from the corresponding node or edge definition.

    View graph schemas

    You can visualize your graph schema in a notebook.

    Update a graph schema

    To make any change to an existing graph's schema, you must redefine the graph schema by using the CREATE PROPERTY GRAPH statement.

    Delete a graph schema

    To delete a property graph, use the DROP PROPERTY GRAPH statement .

    What's next
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: