Add 2.1 known limitations

[sploiselle]

Create known limitations page for 2.1, as well as perform very minor cleanup on old issues. Descriptions provided by engineering in all cases except for the DISTINCT issue with JSON, which I worked with Justin on.

Adds docs-done to

Once merged, the following issues should have the docs-done label added

• cli/sql: support COPY FROM STDIN in the sql shell cockroach#16392
• cli/decommission: decommission hangs with 3-node cluster cockroach#18029
• sql: PARTITION BY does not support placeholders cockroach#19464
• sql: boundary dates are broken cockroach#20136
• sql: CTE name resolution can't pass through VALUES or UNION clauses cockroach#22418
• sql: current sequence value not checked when updating min/max value cockroach#23719
• sql: SELECT DISTINCT jsoncol->foo is broken cockroach#24436
• sql: merge schema changes to the same descriptor together when issued in the same txn cockroach#24919
• sql: can't perform mutiple deletes when there are self-referencing foreign keys cockroach#25809
• sql: group by does not conform with postgres cockroach#26709
• sql: users surprised by the non-atomicity of TRUNCATE cockroach#27953
• sql: make GROUP BY recognize projection aliases cockroach#28059
• ui: cluster viz: normalize CPU % to 0-100 by # cores cockroach#28724
• sql: old sqlalchemy adapter that seems to work with 1.x and 2.0 doesn't with 2.1. The new one does. cockroach#28772
• opt: like_escape is slower than SELECT LIKE cockroach#30192
• ui: Statements Page timing for CREATE INDEX wrong cockroach#30381
• stability: improve handling of indexes with large column values cockroach#30515
• sql: Cannot use AOST on the select query of an insert cockroach#30534
• pgwire: application_name in connection URL only partially works cockroach#31766

[cockroach-teamcity]

This change is 

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/d0e43cb24ac6e66f3d834e6a58909a4ea247d062/

[jseldess]

, with a few nits. Thanks very much, @sploiselle!

Reviewable status: complete! 0 of 0 LGTMs obtained (and 1 stale)

---

v2.1/known-limitations.md, line 37 at r1 (raw file):

The use of tables with very large primary or secondary index keys (>32KB) can result in excessive memory usage. Specifically, if the primary or secondary index key is larger than 32KB the default indexing scheme for RocksDB SSTables breaks down and causes the index to be excessively large. The index is pinned in memory by default for performance.

To work around this issue, we recommend limiting the size of primary and secondary keys to 4KB, which you must account for manually. Note that columns most columns are 8B (exceptions being `STRING` and `JSON`), which still allows for very complex key structures.

Remove first columns from columns most columns.

---

v2.1/known-limitations.md, line 49 at r1 (raw file):

### Using `LIKE...ESCAPE` in `WHERE` and `HAVING` constraints

CockroachDB tries to optimize most comparisons operators in `WHERE` and `HAVING` clauses into constraints on SQL indexes by only accessing selected rows. This is done for `LIKE` clauses when a common prefix for all selected rows can be determined in the search pattern (e.g. `... LIKE 'Joe%'`). However, this optimization is not yet available if the `ESCAPE` keyword is also used.

nit: e.g. > e.g.,

---

v2.1/known-limitations.md, line 55 at r1 (raw file):

### Using SQLAlchemy with CockroachDB

Users of the SQLAlchemy adapter provided by Cockroach Labs must [upgrade the adapter to the latest release](https://github.com/cockroachdb/cockroachdb-python) before they upgrade to CockroachDB 2.1.

Would you mind adding this note to the 2.1 SQLAlchemy tutorial as well?

---

v2.1/known-limitations.md, line 74 at r1 (raw file):

`TRUNCATE` is not a DML statement, but instead works as a DDL statement. Its limitations are the same as other DDL statements, which are outlined in [Online Schema Changes
: Limitations](https://www.cockroachlabs.com/docs/v2.1/online-schema-changes.html#limitations)

Let's use a relative link instead: [Online Schema Changes: Limitations](online-schema-changes.html#limitations)

---

v2.1/known-limitations.md, line 82 at r1 (raw file):
I think the sentence would read better with the examples in parentheses:

at the end of the GROUP BY list (e.g., SELECT...), or DISTINCT should be used (e.g., SELECT...).

---

v2.1/known-limitations.md, line 88 at r1 (raw file):

### Cannot `DELETE` multiple rows with self-referencing FKs

Because CockroachDB checks foreign keys eagerly (i.e. per row), it cannot trivially delete multiple rows from a table with a self-referencing foreign key.

nit: i.e.,

---

v2.1/known-limitations.md, line 98 at r1 (raw file):

CockroachDB does not currently key-encode JSON values, which prevents `DISTINCT` filters from working on them.

As a workaround, you can return the JSON field's values to a `string` using the `->>` operator, e.g. `SELECT DISTINCT col->>'field'...`.

nit: e.g.,

---

v2.1/known-limitations.md, line 110 at r1 (raw file):

### Using common table expressions in `VALUES` and `UNION` clauses

When the [cost-based optimizer](https://www.cockroachlabs.com/docs/v2.1/cost-based-optimizer.html) is disabled (which is the default), or when it does not support a query, a common table expression defined outside of a `VALUES` or `UNION `clause will not be available inside it. For example `...WITH a AS (...) SELECT ... FROM (VALUES(SELECT * FROM a))`.

Let's make the link relative: cost-based optimizer](cost-based-optimizer.html)

---

v2.1/known-limitations.md, line 118 at r1 (raw file):

### Conversion of integers to date/time values

CockroachDB supports an experimental extension to the SQL standard where an integer value can be converted to a `DATE`/`TIME`/`TIMESTAMP` value, taking the number as a number of seconds since the Unix epoch. This conversion is currently only well defined for a small range of integers and values that a large in magnitude will cause conversion errors.

Somethings off in the last sentence, but I can't quite figure out what.

---

v2.1/known-limitations.md, line 122 at r1 (raw file):

[Tracking GitHub Issue](https://github.com/cockroachdb/cockroach/issues/20136)

### Cannot decommission nodes

I'm surprised we want to call this out as a limitations. This feels like something we would never want to fix?

---

v2.1/known-limitations.md, line 132 at r1 (raw file):

### Importing data using the PostgreSQL COPY protocol

Currently the built-in SQL shell provided with CockroachDB (`cockroach sql` / `cockroach demo`) does not support importing data using the `COPY` statement. Users can use the `psql` client command provided with PostgreSQL to load this data into CockroachDB instead. For details see [Import from generic SQL dump](https://www.cockroachlabs.com/docs/stable/import-data.html#import-from-generic-sql-dump).

nits:

• Currently,
• For details, see

[sploiselle]

@jseldess Getting clarification on INT->>DATE, but everything else is done.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/2296029744e2179c2cab6b8b25aff2e36f82977a/

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/d80f92f835c3893e2173b338fc763f350512d089/