diff --git a/content/shared/influxdb3-admin/distinct-value-cache/create.md b/content/shared/influxdb3-admin/distinct-value-cache/create.md index c897c0dbf8..560208c345 100644 --- a/content/shared/influxdb3-admin/distinct-value-cache/create.md +++ b/content/shared/influxdb3-admin/distinct-value-cache/create.md @@ -69,6 +69,59 @@ influxdb3 create distinct_cache \ {{% /show-in %}} +## Use the HTTP API + +To use the HTTP API to create a Distinct Value Cache, send a `POST` request to the `/api/v3/configure/distinct_cache` endpoint. + +{{% api-endpoint method="POST" endpoint="/api/v3/configure/distinct_cache" api-ref="/influxdb3/version/api/v3/#operation/PostConfigureDistinctCache" %}} + +{{% code-placeholders "(DATABASE|TABLE|DVC)_NAME|AUTH_TOKEN|COLUMNS|MAX_(CARDINALITY|AGE)" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "table": "TABLE_NAME", + "name": "DVC_NAME", + "columns": ["COLUMNS"], + "max_cardinality": MAX_CARDINALITY, + "max_age": MAX_AGE + }' +``` + +{{% /code-placeholders %}} + +### Example + +```bash +curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \ + --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ + --json '{ + "db": "example-db", + "table": "wind_data", + "name": "windDistinctCache", + "columns": ["country", "county", "city"], + "max_cardinality": 10000, + "max_age": 86400 + }' +``` + +**Response codes:** + +- `201` : Success. The distinct cache has been created. +- `204` : Not created. A distinct cache with this configuration already exists. +- `400` : Bad request. + + +> [!Note] +> #### API parameter differences +> +> - **Columns format**: The API uses a JSON array (`["country", "county", "city"]`) +> instead of the CLI's comma-delimited format (`country,county,city`). +> - **Maximum age format**: The API uses seconds (`86400`) instead of the CLI's +> [humantime format](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) (`24h`, `1 day`). + Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: diff --git a/content/shared/influxdb3-admin/distinct-value-cache/query.md b/content/shared/influxdb3-admin/distinct-value-cache/query.md index 55e0ce4d0d..9ec48d4eea 100644 --- a/content/shared/influxdb3-admin/distinct-value-cache/query.md +++ b/content/shared/influxdb3-admin/distinct-value-cache/query.md @@ -31,3 +31,37 @@ FROM WHERE country = 'Spain' ``` + +## Use the HTTP API + +To use the HTTP API to query cached data, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint and include the [`distinct_cache()`](/influxdb3/version/reference/sql/functions/cache/#distinct_cache) function in your query. + +{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}} + +{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}} + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "q": "SELECT * FROM distinct_cache('\''TABLE_NAME'\'', '\''CACHE_NAME'\'')", + "format": "json" + }' +``` + +{{% /code-placeholders %}} + +## Example with WHERE clause + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ + --json '{ + "db": "example-db", + "q": "SELECT room, temp FROM last_cache('\''home'\'', '\''homeCache'\'') WHERE room = '\''Kitchen'\''", + "format": "json" + }' +``` diff --git a/content/shared/influxdb3-admin/distinct-value-cache/show.md b/content/shared/influxdb3-admin/distinct-value-cache/show.md index 0de0e2ac08..fd825711d1 100644 --- a/content/shared/influxdb3-admin/distinct-value-cache/show.md +++ b/content/shared/influxdb3-admin/distinct-value-cache/show.md @@ -67,3 +67,44 @@ In the examples above, replace the following: - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{< product-name >}} {{% show-in "enterprise" %}}admin {{% /show-in %}} authentication token + +## Use the HTTP API + +To use the HTTP API to query and output cache information from the system table, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint. + +{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}} + +{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}} + +### Query all caches + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "q": "SELECT * FROM system.distinct_caches", + "format": "json" + }' + ``` + +{{% /code-placeholders %}} + +## Query specific cache details + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|CACHE_NAME" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "q": "SELECT * FROM system.distinct_caches WHERE name = '\''CACHE_NAME'\''", + "format": "json" + }' +``` + +{{% /code-placeholders %}} + diff --git a/content/shared/influxdb3-admin/last-value-cache/create.md b/content/shared/influxdb3-admin/last-value-cache/create.md index febc66f83e..5e57de0777 100644 --- a/content/shared/influxdb3-admin/last-value-cache/create.md +++ b/content/shared/influxdb3-admin/last-value-cache/create.md @@ -80,6 +80,59 @@ influxdb3 create last_cache \ {{% /show-in %}} +## Use the HTTP API + +To use the HTTP API to create a Last Value Cache, send a `POST` request to the `/api/v3/configure/last_cache` endpoint. + +{{% api-endpoint method="POST" endpoint="/api/v3/configure/last_cache" api-ref="/influxdb3/version/api/v3/#operation/PostConfigureLastCache" %}} + +{{% code-placeholders "(DATABASE|TABLE|LVC)_NAME|AUTH_TOKEN|(KEY|VALUE)_COLUMNS|COUNT|TTL" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "table": "TABLE_NAME", + "name": "LVC_NAME", + "key_columns": ["KEY_COLUMNS"], + "value_columns": ["VALUE_COLUMNS"], + "count": COUNT, + "ttl": TTL + }' + ``` + + {{% /code-placeholders %}} + + ### Example + +```bash + curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \ + --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ + --json '{ + "db": "example-db", + "table": "home", + "name": "homeLastCache", + "key_columns": ["room", "wall"], + "value_columns": ["temp", "hum", "co"], + "count": 5, + "ttl": 14400 + }' +``` + +**Response codes:** + +- `201` : Success. Last cache created. +- `400` : Bad request. +- `401` : Unauthorized. +- `404` : Cache not found. +- `409` : Cache already exists. + +> [!Note] +> #### API parameter differences +> Column format: The API uses JSON arrays (["room", "wall"]) instead of the CLI's comma-delimited format (room,wall). +> TTL format: The API uses seconds (14400) instead of the CLI's humantime format (4h, 4 hours). + Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: @@ -116,4 +169,4 @@ The cache imports the distinct values from the table and starts caching them. > > The LVC is stored in memory, so it's important to consider the size and persistence > of the cache. For more information, see -> [Important things to know about the Last Value Cache](/influxdb3/version/admin/last-value-cache/#important-things-to-know-about-the-last-value-cache). +> [Important things to know about the Last Value Cache.](/influxdb3/version/admin/last-value-cache/#important-things-to-know-about-the-last-value-cache) diff --git a/content/shared/influxdb3-admin/last-value-cache/delete.md b/content/shared/influxdb3-admin/last-value-cache/delete.md index b06ba5eb9c..8f61adaa6e 100644 --- a/content/shared/influxdb3-admin/last-value-cache/delete.md +++ b/content/shared/influxdb3-admin/last-value-cache/delete.md @@ -23,6 +23,33 @@ influxdb3 delete last_cache \ ``` {{% /code-placeholders %}} +## Use the HTTP API + +To use the HTTP API to delete a Last Value Cache, send a `DELETE` request to the `/api/v3/configure/last_cache` endpoint with query parameters. + +{{% api-endpoint method="DELETE" endpoint="/api/v3/configure/last_cache" api-ref="/influxdb3/core/api/v3/#operation/DeleteConfigureLastCache" %}} + +{{% code-placeholders "(DATABASE|TABLE|LVC)_NAME|AUTH_TOKEN" %}} +```bash +curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=DATABASE_NAME&table=TABLE_NAME&name=LVC_NAME" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` +{{% /code-placeholders %}} + +## Example + +```bash +curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=example-db&table=home&name=homeLastCache" \ + --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" +``` + +**Response codes:** + +- `200` : Success. The last cache has been deleted. +- `400` : Bad request. +- `401` : Unauthorized. +- `404` : Cache not found. + Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: diff --git a/content/shared/influxdb3-admin/last-value-cache/show.md b/content/shared/influxdb3-admin/last-value-cache/show.md index cf0aa7019c..623e1c57fa 100644 --- a/content/shared/influxdb3-admin/last-value-cache/show.md +++ b/content/shared/influxdb3-admin/last-value-cache/show.md @@ -66,3 +66,43 @@ In the examples above, replace the following: - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{< product-name >}} {{% show-in "enterprise" %}}admin {{% /show-in %}} authentication token + +## Use the HTTP API + +To use the HTTP API to query and output cache information from the system table, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint. + +{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}} + +{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}} + +### Query all last value caches + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "q": "SELECT * FROM system.last_caches", + "format": "json" + }' + ``` + +{{% /code-placeholders %}} + +## Query specific cache details + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|CACHE_NAME" %}} + +```bash +curl -X POST "https://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{ + "db": "DATABASE_NAME", + "q": "SELECT * FROM system.last_caches WHERE name = '\''CACHE_NAME'\''", + "format": "json" + }' +``` + +{{% /code-placeholders %}} \ No newline at end of file