anchor.diff:  
   == User Guide
   
  -The following section describes recommendations and best practices for how to best use the Cloud Spanner Hibernate Dialect.
  -
  -=== Use Generated UUIDs for ID Generation
  +This guide contains a variety of best practices for using Hibernate with Spanner which can significantly improve the performance of your application.
  +
  +=== Schema Creation and Entity Design
  +
  +Hibernate generates statements based on your Hibernate entity design. Following these practices can result in better DDL and DML statement generation which can improve performance.
  +
  +==== Use Generated UUIDs for ID Generation
   
   The Universally Unique Identifier (UUID) is the preferred ID type in Cloud Spanner because it avoids hotspots as the system divides data among servers by key ranges.
  -A monotonically increasing integer key would also work, but can be less performant.
  -
  -For this reason, if you are using generated IDs in your code, you should configure UUID generation like this:
  +UUIDs are strongly preferred over sequentially increasing IDs for this reason.
  +
  +It is also recommended to use Hibernate's `@GeneratedValue` annotation to generate this UUID automatically; this can reduce the number of statements that Hibernate generates to perform an insert because it does not need to run extra `SELECT` statements to see if the record already exists in the table.
  +
  +You can configure UUID generation like below:
   
   [source, java]
   ----
  
positive.code: 
  The property is set to `100` as an example; you may experiment with the batch size to see what works best for your application.
  
  === Query Optimization
  
  The https://cloud.google.com/spanner/docs/query-syntax[Cloud Spanner SQL syntax] offers a variety of query hints to tune and optimize the performance of queries.
  If you find that you need to take advantage of this feature, you can achieve this in Hibernate using native SQL queries.
  
negative.code: 
  Also, you may consult the https://cloud.google.com/spanner/docs/sql-best-practices[Cloud Spanner documentation] on general recommendations for optimizing performance.
  
  == Cloud Spanner Hibernate ORM Limitations
  
  The Cloud Spanner Hibernate Dialect supports most of the standard Hibernate and Java Persistence annotations, but there are minor differences in supported features because of differences in Cloud Spanner from other traditional SQL databases.
  
  [options="header"]
  |===
  | Unsupported Feature | Description
  | Large DML Transactions | Each Spanner transaction may only have up to 20,000 operations which modify rows of a table.
  | Catalog and schema scoping for table names | Tables name references cannot contain periods or other punctuation.
  | Column default values | The dialect does not set default values based on the `@ColumnDefault` annotation, because Cloud Spanner does not support column defaults in the DDL.
  |===
  
  === Large DML Transactions Limits
  
  Cloud Spanner has a mutation limit on each transaction - each Spanner transaction https://cloud.google.com/spanner/quotas#limits_for_creating_reading_updating_and_deleting_data[may only have up to 20,000 operations which modify rows of a table].
  
  NOTE: Deleting a row counts as one operation and inserting/updating a single row will https://cloud.google.com/spanner/quotas#note2[count as a number of operations equal to the number of affected columns].
  For example if one inserts a row that contains 5 columns, it counts as 5 modify operations for the insert.
  
  Consequently, users must take care to avoid encountering these constraints.
  
  1. We recommend being careful with the use of `CASCADE_TYPE.ALL` in Entity annotations because, depending on the application, it might trigger a large number of entities to be deleted in a single transaction and bring you over the 20,000 limit.
  2. Also, when persisting a collection of entities, be mindful of the 20,000 mutations per transaction constraint.
  
  === Catalog/Schema Table Names
  
  The Cloud Spanner Dialect only supports `@Table` with the `name` attribute.
  It does not support table names with catalog and schema components because Spanner table names may not contain punctuation:
  
  [source, java]
  ----
  