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

This document describes the process of migrating your data and application toSpanner Graph. We describe the migration stages and recommended toolsfor each stage, depending on your source database and other factors.

Migrating your graph to Spanner Graph involves the following core stages:

1. Gather your application requirements.
2. Design your Spanner Graph schema.
3. Migrate your application to Spanner Graph.
4. Test and tune Spanner Graph.
5. Migrate your data to Spanner Graph.
6. Validate your data migration.
7. Configure your cutover and failover mechanism.

To optimize your schema and application for performance, you might need toiteratively design your schema, build your application, and test and tuneSpanner Graph.

Gather your application requirements

To design a schema that meets your application needs, gather thefollowing requirements:

• Data modeling
• Common query patterns
• Latency and throughput requirements

Design your Spanner Graph schema

To learn how to design a Spanner Graph schema, seeSpanner Graph schema overview forbasic concepts and seeCreate, update, or drop a Spanner Graph schemafor more examples. To optimize your schema for common query patterns, seeBest practices for designing a Spanner Graph schema.

Migrate your application to Spanner Graph

First read the general Spanner guidance aboutmigrating yourapplicationand then read the guidance in this section to learn the Spanner Graphapplication migration guidance.

Connect to Spanner Graph

To learn how to connect programmatically with Spanner Graph, seeCreate, update, or drop a Spanner Graph schemaand theSpanner Graph queries overview.

Migrate queries

The Spanner Graph query interface is compatible withISO GQL, and it includes additionalopenCypher syntax support. For more information, seeSpanner Graph reference for openCypher users.

Migrate mutations

To migrate your application's mutation logic, you can use Spanner tablemutation mechanisms. For more information, seeInsert, update, or delete Spanner Graphdata.

Test and tune Spanner Graph

The Spanner guidance about how totest and tune schema and application performanceapplies to Spanner Graph. To learnSpanner Graph performance optimization best practices, seeBest practices for designing a Spanner Graph schemaandBest practices for tuning Spanner Graph queries.

Migrate your data to Spanner Graph

To move your data from a relational database, seeMigrate yourdata.

To move data from a graph database or a non-relational database, you can persistdata from the source database into files, upload the files to Cloud Storage,and then import the files using Dataflow. Recommended file formatsinclude AVRO and CSV. For more information, seeRecommended formats for bulkmigration.

Handle Constraints

If your schema has constraints defined on input tables, make sure thoseconstraints aren't violated during data import. Constraints include thefollowing:

• Foreign Keys: A foreign key constraint might be defined for an edge'sreference to a node.
• Interleaving: An edge input table might be interleaved in a node inputtable. This interleaving defines a parent-child relationship, with theimplicit constraint that the parent must exist before the child is created.

The parent in an interleaved organization and the referenced entity in theforeign key constraint must be loaded first. This means that you must first loadnodes in the graph and then load the edges. When you load edges before you loadthe nodes that the edges connect to, you might encounter errors during theloading process that indicate certain keys don't exist.

To achieve the correct import order, use Google-provided templates to defineseparate Dataflow jobs for each stage and then run the jobs insequence. For example, you might run one Dataflow job to importnodes, and then run another Dataflow job to import edges.Alternatively, you might write acustom Dataflowjob that manages the import sequence.

For more information about Google-provided templates, see the following:

• Cloud Storage Text to Spanner template.
• Cloud Storage Avro to Spanner template.

If you import in the wrong order, the job might fail, or only part of your datamight be migrated. If only part of your data is migrated, perform the migrationagain.

Improve data loading efficiency

To improve data loading efficiency, create secondary indexes and define foreignkeys after you import your data to Spanner. This approach is onlypossible for initial bulk loading or during migration with downtime.

Validate your data migration

After you migrate your data, perform basic queries to verify datacorrectness. Run the following queries on both source and destination databasesto verify that the results match:

• Count the number of nodes and edges.
• Count the number of nodes and edges per label.
• Compute stats (count, sum, avg, min, max) on each node and edge property.

Configure cutover and failover mechanism

Configure your cutover and failover mechanisms.

What's next

• Compare Spanner Graph and openCypher.
• Troubleshoot Spanner Graph.