Merge pull request #3104 from knz/20180505-numbering

Create FAQs for numbering problems.

_includes/faq/differences-between-numberings.md

@@ -0,0 +1,12 @@
+
+| Property                            | UUID generated with `uuid_v4()`         | INT generated with `unique_rowid()`           | Sequences                      |
+|-------------------------------------|-----------------------------------------|-----------------------------------------------|--------------------------------|
+| Size                                | 16 bytes                                | 8 bytes                                       | 1 to 8 bytes                   |
+| Ordering properties                 | Unordered                               | Highly time-ordered                           | Highly time-ordered            |
+| Performance cost at generation      | Small, scalable                         | Small, scalable                               | Variable, can cause contention |
+| Value distribution                  | Uniformly distributed (128 bits)        | Contains time and space (node ID) components  | Dense, small values            |
+| Data locality                       | Maximally distributed                   | Values generated close in time are co-located | Highly local                   |
+| INSERT latency when used as key     | Small, insensitive to concurrency       | Small, but increases with concurrent INSERTs  | Higher                         |
+| INSERT throughput when used as key  | Highest                                 | Limited by max throughput on 1 node           | Limited by max throughput on 1 node |
+| Read throughput when used as key    | Highest (maximal parallelism)           | Limited                                       | Limited                        |
+

_includes/faq/sequential-numbers.md

@@ -0,0 +1,22 @@
+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,32 @@
+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.
+
+Consider also that the values generated by `unique_rowid()`, described
+in the previous FAQ entries, also provide an approximate time ordering.
+
+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,6 +14,21 @@ 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.

v2.1/sql-faqs.md

@@ -14,6 +14,21 @@ 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.