Create FAQs for numbering problems.

_includes/faq/differences-between-numberings.md

@@ -0,0 +1,7 @@
+| Property                       | UUID generated with `uuid_v4()`         | INT generated with `unique_rowid()`          | Sequences                      |
+|--------------------------------|-----------------------------------------|----------------------------------------------|--------------------------------|
+| Size                           | 16 bytes                                | 8 bytes                                      | 1 to 8 bytes                   |
+| Ordering properties            | Unordered                               | Somewhat time-ordered                        | Highly time-ordered            |
+| Value distribution             | Uniformly distributed (128 bits)        | Contains time and space (node ID) components | Dense, small values            |
+| Performance cost at generation | Small, scalable                         | Small, scalable                              | Variable, can cause contention |
+| Locality                       | Maximally distributed, least contention | Somewhat local, may cause INSERT contention  | Highly local, most INSERT contention |

_includes/faq/sequential-numbers.md

@@ -0,0 +1,20 @@
+Sequential numbers can be generated in CockroachDB using the built-in
+function `unique_rowid()` or using [SQL sequences](create-sequence.html).
+
+{{site.data.alerts.callout_info}}Unless you need roughly-ordered
+numbers, we recommend to use `UUID` values instead. See the previous
+FAQ for details.{{site.data.alerts.end}}
+
+{{site.data.alerts.callout_info}}Sequences produce <emph>unique</emph>
+values, however not all values are guaranteed to be produced (e.g.,
+when a transaction is canceled after it consumes a value) and the
+values may be slightly reordered (e.g., when a transaction that
+consumes a lower sequence number commits after a transaction that
+consumes a higher number).{{site.data.alerts.end}}
+
+{{site.data.alerts.callout_info}}For maximum performance, avoid using
+sequences or <code>unique_rowid()</code> to generate row IDs or
+indexed columns. This is because sequence values and values generated
+by <code>unique_rowid()</code> are logically close to each other and
+can cause contention on few data ranges during inserts. Instead,
+prefer <code>UUID</code> identifiers.{{site.data.alerts.end}}

_includes/faq/sequential-transactions.md

@@ -0,0 +1,29 @@
+We find that most use cases that appear to ask for a strong time-based
+write ordering can be solved with other, more distribution-friendly
+solutions instead. For example, CockroachDB's [time travel queries
+(`AS OF SYSTEM
+TIME`)](https://www.cockroachlabs.com/blog/time-travel-queries-select-witty_subtitle-the_future/)
+support the following:
+
+- Paginate through all the changes to a table or dataset.
+- Determine the order of changes to data over time.
+- Determine the state of data at some point in the past.
+- Determine the changes to data between two points of time.
+
+Should your application absolutely require it, it is still possible to
+create a strictly monotonic counter in CockroachDB that increases over
+time, as follows:
+
+- initially: `CREATE TABLE cnt(val INT PRIMARY KEY); INSERT INTO cnt(val) VALUES(1);`
+- in each transaction: `INSERT INTO cnt(val) SELECT max(val)+1 FROM cnt RETURNING val;`
+
+This will cause all your INSERT transactions to conflict with each
+other and effectively force the transactions to commit one at a time
+throughout the cluster, which in turn guarantees the values generated
+in this way are strictly increasing over time without gaps. The caveat
+is that performance is severely limited as a result.
+
+Please contact us and describe your situation if you find yourself
+interested in this problem. We would be glad to help you find
+alternative solutions and possibly extend CockroachDB to better match
+your needs.

v2.0/sql-faqs.md

@@ -14,17 +14,17 @@ Currently, you can bulk insert data with batches of [`INSERT`](insert.html) stat
 
 {% include faq/auto-generate-unique-ids_v1.1.html %}
 
-## How do I get the last ID/SERIAL value inserted into a table?
+## How do I generate unique, slowly increasing sequential numbers in CockroachDB?
 
-There’s no function in CockroachDB for returning last inserted values, but you can use the [`RETURNING` clause](insert.html#insert-and-return-values) of the `INSERT` statement.
+{% include faq/sequential-numbers.md %}
 
-For example, this is how you’d use `RETURNING` to return an auto-generated [`SERIAL`](serial.html) value:
+## What are the differences between `UUID`, sequences and `unique_rowid()`?
 
-~~~ sql
-> CREATE TABLE users (id SERIAL, name STRING);
+{% include faq/differences-between-numberings.md %}
 
-> INSERT INTO users (name) VALUES ('mike') RETURNING id;
-~~~
+## How do I order writes to a table to closely follow time in CockroachDB?
+
+{% include faq/sequential-transactions.md %}
 
 ## Does CockroachDB support `JOIN`?
 
@@ -34,6 +34,18 @@ To learn more, see our blog posts on CockroachDB's JOINs:
 - [Modesty in Simplicity: CockroachDB's JOIN](https://www.cockroachlabs.com/blog/cockroachdbs-first-join/).
 - [On the Way to Better SQL Joins](https://www.cockroachlabs.com/blog/better-sql-joins-in-cockroachdb/)
 
+## How do I get the last ID/SERIAL value inserted into a table?
+
+There’s no function in CockroachDB for returning last inserted values, but you can use the [`RETURNING` clause](insert.html#insert-and-return-values) of the `INSERT` statement.
+
+For example, this is how you’d use `RETURNING` to return an auto-generated [`SERIAL`](serial.html) value:
+
+~~~ sql
+> CREATE TABLE users (id SERIAL, name STRING);
+
+> INSERT INTO users (name) VALUES ('mike') RETURNING id;
+~~~
+
 ## When should I use interleaved tables?
 
 [Interleaving tables](interleave-in-parent.html) improves query performance by optimizing the key-value structure of closely related tables, attempting to keep data on the same key-value range if it's likely to be read and written together.

v2.1/sql-faqs.md

@@ -14,6 +14,18 @@ Currently, you can bulk insert data with batches of [`INSERT`](insert.html) stat
 
 {% include faq/auto-generate-unique-ids_v1.1.html %}
 
+## How do I generate unique, slowly increasing sequential numbers in CockroachDB?
+
+{% include faq/sequential-numbers.md %}
+
+## What are the differences between `UUID`, sequences and `unique_rowid()`?
+
+{% include faq/differences-between-numberings.md %}
+
+## How do I order writes to a table to closely follow time in CockroachDB?
+
+{% include faq/sequential-transactions.md %}
+
 ## How do I get the last ID/SERIAL value inserted into a table?
 
 There’s no function in CockroachDB for returning last inserted values, but you can use the [`RETURNING` clause](insert.html#insert-and-return-values) of the `INSERT` statement.