Support inserting into compressed chunks (#74)

* Support inserting into compressed chunks

* Apply suggestions from code review

Co-authored-by: Lana Brindley <github@lanabrindley.com>

* Update timescaledb/how-to-guides/compression/compression-basics.md

Co-authored-by: Ryan Booz <ryan@timescale.com>

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Nuno Santos <nuno@timescale.com>

* Apply suggestions from code review

Co-authored-by: Nuno Santos <nuno@timescale.com>

* Apply suggestions from code review

Co-authored-by: Nuno Santos <nuno@timescale.com>

* Apply suggestions from code review

Co-authored-by: Ryan Booz <ryan@timescale.com>
Co-authored-by: Jônatas Davi Paganini <jonatasdp@gmail.com>

Co-authored-by: Lana Brindley <github@lanabrindley.com>
Co-authored-by: Ryan Booz <ryan@timescale.com>
Co-authored-by: Nuno Santos <nuno@timescale.com>
Co-authored-by: Jônatas Davi Paganini <jonatasdp@gmail.com>

api/compression.md

@@ -11,14 +11,42 @@ policy](/compression/add_compression_policy/) for when to compress chunks.
 Advanced usage of compression allows users to [compress chunks
 manually](/compression/compress_chunk), instead of automatically as they age.
 
+Compressed chunks have the following limitations:
+- `ROW LEVEL SECURITY` is not supported.
+- Constraints are not fully supported:
+    - Unique constraints (`UNIQUE`) are restricted to compression `SEGMENTBY`
+      and `ORDER BY` columns.
+    - Primary Keys (`PRIMARY KEY`) are restricted to compression `SEGMENTBY`
+      and `ORDER BY` columns.
+    - Constraints are restricted to compression `SEGMENTBY` columns when
+    applicable. Otherwise they are unsupported.
+
 ### Restrictions
 
-The current version does not support altering or inserting data into compressed
-chunks. The data can be queried without any modifications, however if you
-need to backfill or update data in a compressed chunk you will need to
-decompress the chunk(s) first.
+In general, compressing a hypertable does impose some limitations on the types
+of data modifications that can occur on data inside a compressed chunk. 
+The table below provides a brief outline of allowed modifications 
+based on the version of TimescaleDB you are currently running.
+
+|TimscaleDB Version|Supported data modifications on compressed chunks|
+|---|---|
+| 1.5 - 2.0 | Data and schema modifications supported. |
+| 2.1 - 2.2 | Schema may be modified on compressed hypertables. Data modification not supported. |
+| 2.3 | Schema modifications and basic insert of new data are allowed. Deleting, updating and some advanced insert statements are not supported. |
 
 Starting with TimescaleDB 2.1, users have the ability to modify the schema
 of hypertables that have compressed chunks.
 Specifically, you can add columns to and rename existing columns of 
-such compressed hypertables.
+such compressed hypertables.
+
+Starting with TimescaleDB 2.3, users have the ability to insert data into compressed chunks 
+and to enable compression policies on distributed hypertables.
+
+Altering data of compressed chunks still has some limitations:
+  - You cannot execute `UPDATE` or `DELETE` statements on compressed chunks.
+  - `INSERT` is not fully supported on compressed chunks:
+    - You cannot use the `ON CONFLICT` clause  i.e. upserts are not supported.
+    - You cannot use the `OVERRIDING` clause.
+    - You cannot use the `RETURNING` clause.
+  - Triggers are not fully supported when inserting into compressed chunks:
+    - You cannot use `AFTER INSERT` row-level triggers (`FOR EACH ROW`).

timescaledb/how-to-guides/compression/backfill-historical-data.md

@@ -96,14 +96,14 @@ CALL run_job(<job_id>);
 ## Future Work [](future-work)
 
 One of the current limitations of TimescaleDB is that once chunks are converted
-into compressed column form, we do not currently allow further modifications
-of the data (e.g., inserts, updates, deletes) or the schema without manual decompression,
-except as noted [above](#compression-schema-changes). In other words, chunks are
-immutable in compressed form. Attempts to modify the chunks' data will either
-error or fail silently (as preferred by users). We plan to remove this limitation
-in future releases.
+into compressed column form, we do not allow updates and deletes of the data 
+or changes to the schema without manual decompression, except as noted [above][compression-schema-changes]. 
+In other words, chunks are partially immutable in compressed form. 
+Attempts to modify the chunks' data in those cases will either error or fail silently (as preferred by users). 
+We plan to remove this limitation in future releases.
 
 
 [timescaledb-extras]: https://github.com/timescale/timescaledb-extras
+[compression-schema-changes]: /how-to-guides/compression/modify-a-schema/
 [timescaledb-extras-backfill]: https://github.com/timescale/timescaledb-extras/blob/master/backfill.sql
 [run-job]: /api/:currentVersion:/actions-and-automation/run_job/

timescaledb/how-to-guides/compression/compression-basics.md

@@ -83,19 +83,15 @@ for choosing the age at which to compress the data is when your query patterns
 change from shallow and wide to deep and narrow.
 
 The other thing to consider is that modifications to chunks that have been compressed
-are inefficient. In fact, the current version of compression disallows INSERTS, UPDATES,
-and DELETES on compressed chunks completely (although you can manually decompress
-the chunk to modify it). Because of this current limitation, you want to compress
-a chunk only after it is unlikely to be modified further. The amount of delay
-you should add to chunk compression to minimize the need to decompress chunks will be different
-for each use case, but remember to be mindful of out-of-order data.
+are inefficient. In fact, the current version of compression does not support UPDATES
+and DELETES on compressed chunks (although you can manually decompress the chunk to modify it). 
+Because of this current limitation, you want to compress a chunk only after it is unlikely to be modified further. The amount of delay you should add to chunk compression to minimize the need to decompress chunks 
+will be different for each use case, but remember to be mindful of out-of-order data.
 
 <highlight type="warning">
 The current release of TimescaleDB supports the ability to query data in
-compressed chunks. However, it does not support inserts or updates of data into
+compressed chunks. However, it does not support updates of data into
 compressed chunks.
-
-The ability to insert into compressed chunks is currently slated for TimescaleDB 2.3.
 </highlight>
 
 With regards to compression, a chunk can be in one of three states: active (uncompressed),

timescaledb/how-to-guides/compression/decompress-chunks.md

@@ -28,8 +28,13 @@ SELECT tableoid::regclass FROM metrics
 ```
 
 Decompression might often be employed in the event that you need to backfill or
-update data that lives in a compressed chunk, as TimescaleDB does not currenty
-support modifying (inserting into, updating, deleted from) compressed chunks.
+update data that lives in a compressed chunk, as TimescaleDB only partially
+supports modifying (inserting into, not updating or deleting from) compressed
+chunks.
+
+Moreover, inserting into compressed chunks is more computationally expensive
+when compared to inserting data into an uncompressed chunk. You should consider
+decompressing the chunk before backfilling huge amounts of data.
 
 Next we walk you through the instructions for preparing your table for
 inserting or backfilling data.   The general approach has four steps: