Skip to content

Commit ae503f7

Browse files
jstirnamanjstirnaman
authored
Merge pull request #6277 from influxdata/feature/pr-5974-add-api-examples-to-cache-guides
docs(api): adding api examples to DVC and LVC
2 parents 2d07f6f + 7d63419 commit ae503f7

File tree

6 files changed

+249
-1
lines changed

6 files changed

+249
-1
lines changed

‎content/shared/influxdb3-admin/distinct-value-cache/create.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,59 @@ influxdb3 create distinct_cache \
6969
<!--------------------------- END ENTERPRISE EXAMPLE -------------------------->
7070
{{% /show-in %}}
7171

72+
## Use the HTTP API
73+
74+
To use the HTTP API to create a Distinct Value Cache, send a `POST` request to the `/api/v3/configure/distinct_cache` endpoint.
75+
76+
{{% api-endpoint method="POST" endpoint="/api/v3/configure/distinct_cache" api-ref="/influxdb3/version/api/v3/#operation/PostConfigureDistinctCache" %}}
77+
78+
{{% code-placeholders "(DATABASE|TABLE|DVC)_NAME|AUTH_TOKEN|COLUMNS|MAX_(CARDINALITY|AGE)" %}}
79+
80+
```bash
81+
curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \
82+
--header "Authorization: Bearer AUTH_TOKEN" \
83+
--json '{
84+
"db": "DATABASE_NAME",
85+
"table": "TABLE_NAME",
86+
"name": "DVC_NAME",
87+
"columns": ["COLUMNS"],
88+
"max_cardinality": MAX_CARDINALITY,
89+
"max_age": MAX_AGE
90+
}'
91+
```
92+
93+
{{% /code-placeholders %}}
94+
95+
### Example
96+
97+
```bash
98+
curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \
99+
--header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \
100+
--json '{
101+
"db": "example-db",
102+
"table": "wind_data",
103+
"name": "windDistinctCache",
104+
"columns": ["country", "county", "city"],
105+
"max_cardinality": 10000,
106+
"max_age": 86400
107+
}'
108+
```
109+
110+
**Response codes:**
111+
112+
- `201` : Success. The distinct cache has been created.
113+
- `204` : Not created. A distinct cache with this configuration already exists.
114+
- `400` : Bad request.
115+
116+
117+
> [!Note]
118+
> #### API parameter differences
119+
>
120+
> - **Columns format**: The API uses a JSON array (`["country", "county", "city"]`)
121+
> instead of the CLI's comma-delimited format (`country,county,city`).
122+
> - **Maximum age format**: The API uses seconds (`86400`) instead of the CLI's
123+
> [humantime format](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) (`24h`, `1 day`).
124+
72125
Replace the following:
73126

74127
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:

‎content/shared/influxdb3-admin/distinct-value-cache/query.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,37 @@ FROM
3131
WHERE
3232
country = 'Spain'
3333
```
34+
35+
## Use the HTTP API
36+
37+
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.
38+
39+
{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}}
40+
41+
{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}}
42+
43+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
44+
45+
```bash
46+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
47+
--header "Authorization: Bearer AUTH_TOKEN" \
48+
--json '{
49+
"db": "DATABASE_NAME",
50+
"q": "SELECT * FROM distinct_cache('\''TABLE_NAME'\'', '\''CACHE_NAME'\'')",
51+
"format": "json"
52+
}'
53+
```
54+
55+
{{% /code-placeholders %}}
56+
57+
## Example with WHERE clause
58+
59+
```bash
60+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
61+
--header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \
62+
--json '{
63+
"db": "example-db",
64+
"q": "SELECT room, temp FROM last_cache('\''home'\'', '\''homeCache'\'') WHERE room = '\''Kitchen'\''",
65+
"format": "json"
66+
}'
67+
```

‎content/shared/influxdb3-admin/distinct-value-cache/show.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,44 @@ In the examples above, replace the following:
6767
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}:
6868
your {{< product-name >}} {{% show-in "enterprise" %}}admin {{% /show-in %}}
6969
authentication token
70+
71+
## Use the HTTP API
72+
73+
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.
74+
75+
{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}}
76+
77+
{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}}
78+
79+
### Query all caches
80+
81+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
82+
83+
```bash
84+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
85+
--header "Authorization: Bearer AUTH_TOKEN" \
86+
--json '{
87+
"db": "DATABASE_NAME",
88+
"q": "SELECT * FROM system.distinct_caches",
89+
"format": "json"
90+
}'
91+
```
92+
93+
{{% /code-placeholders %}}
94+
95+
## Query specific cache details
96+
97+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|CACHE_NAME" %}}
98+
99+
```bash
100+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
101+
--header "Authorization: Bearer AUTH_TOKEN" \
102+
--json '{
103+
"db": "DATABASE_NAME",
104+
"q": "SELECT * FROM system.distinct_caches WHERE name = '\''CACHE_NAME'\''",
105+
"format": "json"
106+
}'
107+
```
108+
109+
{{% /code-placeholders %}}
110+

‎content/shared/influxdb3-admin/last-value-cache/create.md

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,59 @@ influxdb3 create last_cache \
8080
<!--------------------------- END ENTERPRISE EXAMPLE -------------------------->
8181
{{% /show-in %}}
8282

83+
## Use the HTTP API
84+
85+
To use the HTTP API to create a Last Value Cache, send a `POST` request to the `/api/v3/configure/last_cache` endpoint.
86+
87+
{{% api-endpoint method="POST" endpoint="/api/v3/configure/last_cache" api-ref="/influxdb3/version/api/v3/#operation/PostConfigureLastCache" %}}
88+
89+
{{% code-placeholders "(DATABASE|TABLE|LVC)_NAME|AUTH_TOKEN|(KEY|VALUE)_COLUMNS|COUNT|TTL" %}}
90+
91+
```bash
92+
curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \
93+
--header "Authorization: Bearer AUTH_TOKEN" \
94+
--json '{
95+
"db": "DATABASE_NAME",
96+
"table": "TABLE_NAME",
97+
"name": "LVC_NAME",
98+
"key_columns": ["KEY_COLUMNS"],
99+
"value_columns": ["VALUE_COLUMNS"],
100+
"count": COUNT,
101+
"ttl": TTL
102+
}'
103+
```
104+
105+
{{% /code-placeholders %}}
106+
107+
### Example
108+
109+
```bash
110+
curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \
111+
--header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \
112+
--json '{
113+
"db": "example-db",
114+
"table": "home",
115+
"name": "homeLastCache",
116+
"key_columns": ["room", "wall"],
117+
"value_columns": ["temp", "hum", "co"],
118+
"count": 5,
119+
"ttl": 14400
120+
}'
121+
```
122+
123+
**Response codes:**
124+
125+
- `201` : Success. Last cache created.
126+
- `400` : Bad request.
127+
- `401` : Unauthorized.
128+
- `404` : Cache not found.
129+
- `409` : Cache already exists.
130+
131+
> [!Note]
132+
> #### API parameter differences
133+
> Column format: The API uses JSON arrays (["room", "wall"]) instead of the CLI's comma-delimited format (room,wall).
134+
> TTL format: The API uses seconds (14400) instead of the CLI's humantime format (4h, 4 hours).
135+
83136
Replace the following:
84137

85138
- {{% 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.
116169
>
117170
> The LVC is stored in memory, so it's important to consider the size and persistence
118171
> of the cache. For more information, see
119-
> [Important things to know about the Last Value Cache](/influxdb3/version/admin/last-value-cache/#important-things-to-know-about-the-last-value-cache).
172+
> [Important things to know about the Last Value Cache.](/influxdb3/version/admin/last-value-cache/#important-things-to-know-about-the-last-value-cache)

‎content/shared/influxdb3-admin/last-value-cache/delete.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,33 @@ influxdb3 delete last_cache \
2323
```
2424
{{% /code-placeholders %}}
2525

26+
## Use the HTTP API
27+
28+
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.
29+
30+
{{% api-endpoint method="DELETE" endpoint="/api/v3/configure/last_cache" api-ref="/influxdb3/core/api/v3/#operation/DeleteConfigureLastCache" %}}
31+
32+
{{% code-placeholders "(DATABASE|TABLE|LVC)_NAME|AUTH_TOKEN" %}}
33+
```bash
34+
curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=DATABASE_NAME&table=TABLE_NAME&name=LVC_NAME" \
35+
--header "Authorization: Bearer AUTH_TOKEN"
36+
```
37+
{{% /code-placeholders %}}
38+
39+
## Example
40+
41+
```bash
42+
curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=example-db&table=home&name=homeLastCache" \
43+
--header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0"
44+
```
45+
46+
**Response codes:**
47+
48+
- `200` : Success. The last cache has been deleted.
49+
- `400` : Bad request.
50+
- `401` : Unauthorized.
51+
- `404` : Cache not found.
52+
2653
Replace the following:
2754

2855
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:

‎content/shared/influxdb3-admin/last-value-cache/show.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,43 @@ In the examples above, replace the following:
6666
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}:
6767
your {{< product-name >}} {{% show-in "enterprise" %}}admin {{% /show-in %}}
6868
authentication token
69+
70+
## Use the HTTP API
71+
72+
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.
73+
74+
{{% api-endpoint method="GET" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/GetExecuteQuerySQL" %}}
75+
76+
{{% api-endpoint method="POST" endpoint="/api/v3/query_sql" api-ref="/influxdb3/version/api/v3/#operation/PostExecuteQuerySQL" %}}
77+
78+
### Query all last value caches
79+
80+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
81+
82+
```bash
83+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
84+
--header "Authorization: Bearer AUTH_TOKEN" \
85+
--json '{
86+
"db": "DATABASE_NAME",
87+
"q": "SELECT * FROM system.last_caches",
88+
"format": "json"
89+
}'
90+
```
91+
92+
{{% /code-placeholders %}}
93+
94+
## Query specific cache details
95+
96+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|CACHE_NAME" %}}
97+
98+
```bash
99+
curl -X POST "https://localhost:8181/api/v3/query_sql" \
100+
--header "Authorization: Bearer AUTH_TOKEN" \
101+
--json '{
102+
"db": "DATABASE_NAME",
103+
"q": "SELECT * FROM system.last_caches WHERE name = '\''CACHE_NAME'\''",
104+
"format": "json"
105+
}'
106+
```
107+
108+
{{% /code-placeholders %}}

0 commit comments

Comments
 (0)