diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 42482045bf..e58f9a4279 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -433,6 +433,7 @@ include::cli:partial$cbcli/nav.adoc[] *** xref:rest-api:rest-compact-post.adoc[Performing Compaction Manually] *** xref:rest-api:rest-autocompact-global.adoc[Auto-Compaction: Global] *** xref:rest-api:rest-autocompact-per-bucket.adoc[Auto-Compaction: Per Bucket] + *** xref:rest-api:rest-magma-compression-per-bucket.adoc[Magma Compression] ** xref:rest-api:rest-rza.adoc[Server Groups API] *** xref:rest-api:rest-servergroup-get.adoc[Getting Group Information] diff --git a/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc b/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc new file mode 100644 index 0000000000..af05df8d1f --- /dev/null +++ b/modules/rest-api/pages/rest-magma-compression-per-bucket.adoc @@ -0,0 +1,132 @@ += Magma Compression +:description: Compression algorithms can be set and listed on a per-bucket basis using the REST API. + +[abstract] +{description} + +Compression settings can be set for an existing bucket. +This requires `Full Admin`, `Cluster Admin` roles, or the `Bucket Admin` role for the specified bucket. + +== HTTP methods and URIs + +[source] +---- +GET /pools/default/buckets/ +POST /pools/default/buckets/ +---- + +== Parameters +The following parameters are available to the REST API +[cols="4,3,3"] +|=== +| Parameter | Type | Description + +| `magmaEnableIndexBlockAutotuning` +| Boolean +| Enable auto-tuning of Magma index block size based on the compression ratio + +Automatically adjusts the pre-compression block-accumulation size so the post-compression (physical) index block size stays close to the configured target block size. + +|`magmaEnableDataBlockAutotuning` +| Boolean +| Enable auto-tuning of Magma data block size based on the compression ratio + +|`magmaIndexCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. + +| Configure the block compression algorithm for the index blocks. + +| `magmaDataCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. +| Configure the block compression algorithm for the data blocks. + +| `magmaCompacteddataCompressionAlgo` +| `snappy`, `lz4`, `none`, `zstd`, or `zstd_` where `` is an integer from 1 to 22. +| Configure the block compression algorithm for the data blocks after compaction. + +Allows colder data to be compressed with a higher compression ratio using `zstd`. +This compression also is scheduled in background compaction threads. + +|=== + +== `Curl` Syntax + +[source, shell] +---- +curl -u : -X GET \ + :8091/pools/default/buckets/ + +curl -u : -X POST \ + :8091//pools/default/buckets/ \ + -d magmaEnableIndexBlockAutotuning=true|false \ + -d magmaEnableDataBlockAutotuning=true|false \ + -d magmaIndexCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + -d magmaDataCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + -d magmaCompacteddataCompressionAlgo=snappy|lz4|none|zstd|zstd_ \ + +---- + +== Responses + +If the call is successful, `200 OK` is given. + +If the operation is performed on a bucket that does not exist, +the REST service responds with a `404 (Object not found)` error. + +Sending the request with an invalid parameter value (sending a number when a Boolean value is expected, for example), returns a `400 (Bad Request)` response. + +You can find the precise nature of the problem by examining the payload in the response: + +[source, jsonlines] +---- +{ +"errors": { + "magmaEnableDataBlockAutotuning": "Value \"ten\" must be a boolean value (true/false, on/off)" + }, + +} +---- + +[NOTE] +==== +Errors in the parameter name result in no change in any of the parameter values, but the REST service responds with `200 (OK)`: + + +==== + + +== Examples + +.Retrieve parameter settings for the bucket. +[source, shell] +---- +curl -u Administrator:password -X GET \ + localhost:8091/pools/default/buckets/travel-sample | jq +---- + +This retrieves all the parameters in the bucket as a JSON string. +If you want to retrieve a parameter or list of parameters, you can add them to `jq` pipe: + +[source, shell] +---- +curl -u Administrator:password -X GET \ + localhost:8091/pools/default/buckets/travel-sample | jq \ + '.magmaEnableDataBlockAutotuning,.magmaEnableDataBlockAutotuning,.magmaIndexCompressionAlgo,.magmaDataCompressionAlgo,.magmaCompacteddataCompressionAlgo' +---- + +.Enable auto-tuning of the bucket index block. +[source, shell] +---- +curl -u Administrator:password -X POST \ + localhost:8091/pools/default/buckets/travel-sample \ + -d magmaEnableIndexBlockAutotuning=true +---- + +.Set the data compression algorithm +[source,shell] +---- +curl -u Administrator:password -X POST \ + localhost:8091/pools/default/buckets/travel-sample \ + -d magmaDataCompressionAlgo=snappy +---- + diff --git a/modules/rest-api/partials/rest-memory-and-storage-table.adoc b/modules/rest-api/partials/rest-memory-and-storage-table.adoc index e5d3fbf0b9..06a09eca8e 100644 --- a/modules/rest-api/partials/rest-memory-and-storage-table.adoc +++ b/modules/rest-api/partials/rest-memory-and-storage-table.adoc @@ -41,4 +41,8 @@ | `POST` | `/pools/default/buckets/[bucket-name]` | xref:rest-api:rest-autocompact-per-bucket.adoc[Auto-Compaction: Per Bucket] + +| `POST` +| `/pools/default/buckets/[bucket-name]` +| xref:rest-api:rest-magma-compression-per-bucket.adoc[Magma compression: Per Bucket] |===