From d2503bc73d0d3090c8d6ff6c234479db0f9b4dd6 Mon Sep 17 00:00:00 2001 From: Dmitry Shmulevich Date: Tue, 15 Feb 2022 09:49:42 -0800 Subject: [PATCH] state store query API: remove 'value' prefix from key names (#2195) Signed-off-by: Dmitry Shmulevich --- .../state-management/howto-state-query-api.md | 60 ++++++++++++------- .../query-api-examples/query1.json | 4 +- .../query-api-examples/query2.json | 2 +- .../query-api-examples/query3-token.json | 10 ++-- .../query-api-examples/query3.json | 10 ++-- .../content/en/reference/api/state_api.md | 10 ++-- 6 files changed, 57 insertions(+), 39 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md index 4a5bd7cca..03cc9a1d7 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md @@ -32,7 +32,7 @@ You can find additional information in the [related links]({{< ref "#related-lin You submit query requests via HTTP POST/PUT or gRPC. The body of the request is the JSON map with 3 entries: `filter`, `sort`, and `page`. -The `filter` is an optional section. It specifies the query conditions in the form of a tree of key/value operations, where the key is the operator and the value is the operands. +The `filter` is an optional section. It specifies the query conditions in the form of a tree, where each node represents either unary or multi-operand operation. The following operations are supported: @@ -43,6 +43,24 @@ The following operations are supported: | `AND` | []operation | operation[0] AND operation[1] AND ... AND operation[n] | | `OR` | []operation | operation[0] OR operation[1] OR ... OR operation[n] | +The `key` in the operand is similar to the JSONPath notation. Each dot in the key indicates a nested JSON structure. Consider for example this structure: +```json +{ + "shape": { + "name": "rectangle", + "dimensions": { + "height": 24, + "width": 10 + }, + "color": { + "name": "red", + "code": "#FF0000" + } + } +} +``` +If you want to compare the value of the color code, the key will be `shape.color.code` + If `filter` section is omitted, the query returns all entries. The `sort` is an optional section and is an ordered array of `key:order` pairs, where `key` is a key in the state store, and the `order` is an optional string indicating sorting order: `"ASC"` for ascending and `"DESC"` for descending. If omitted, ascending order is the default. @@ -93,11 +111,11 @@ This is the [query](../query-api-examples/query1.json): ```json { "filter": { - "EQ": { "value.state": "CA" } + "EQ": { "state": "CA" } }, "sort": [ { - "key": "value.person.id", + "key": "person.id", "order": "DESC" } ] @@ -107,9 +125,9 @@ This is the [query](../query-api-examples/query1.json): An equivalent of this query in SQL is: ```sql SELECT * FROM c WHERE - value.state = "CA" + state = "CA" ORDER BY - value.person.id DESC + person.id DESC ``` Execute the query with the following command: @@ -190,7 +208,7 @@ This is the [query](../query-api-examples/query2.json): ```json { "filter": { - "IN": { "value.person.org": [ "Dev Ops", "Hardware" ] } + "IN": { "person.org": [ "Dev Ops", "Hardware" ] } } } ``` @@ -198,7 +216,7 @@ This is the [query](../query-api-examples/query2.json): An equivalent of this query in SQL is: ```sql SELECT * FROM c WHERE - value.person.org IN ("Dev Ops", "Hardware") + person.org IN ("Dev Ops", "Hardware") ``` Execute the query with the following command: @@ -232,15 +250,15 @@ This is the [query](../query-api-examples/query3.json): "filter": { "OR": [ { - "EQ": { "value.person.org": "Dev Ops" } + "EQ": { "person.org": "Dev Ops" } }, { "AND": [ { - "EQ": { "value.person.org": "Finance" } + "EQ": { "person.org": "Finance" } }, { - "IN": { "value.state": [ "CA", "WA" ] } + "IN": { "state": [ "CA", "WA" ] } } ] } @@ -248,11 +266,11 @@ This is the [query](../query-api-examples/query3.json): }, "sort": [ { - "key": "value.state", + "key": "state", "order": "DESC" }, { - "key": "value.person.id" + "key": "person.id" } ], "page": { @@ -264,11 +282,11 @@ This is the [query](../query-api-examples/query3.json): An equivalent of this query in SQL is: ```sql SELECT * FROM c WHERE - value.person.org = "Dev Ops" OR - (value.person.org = "Finance" AND value.state IN ("CA", "WA")) + person.org = "Dev Ops" OR + (person.org = "Finance" AND state IN ("CA", "WA")) ORDER BY - value.state DESC, - value.person.id ASC + state DESC, + person.id ASC LIMIT 3 ``` @@ -338,15 +356,15 @@ The pagination token is used "as is" in the [subsequent query](../query-api-exam "filter": { "OR": [ { - "EQ": { "value.person.org": "Dev Ops" } + "EQ": { "person.org": "Dev Ops" } }, { "AND": [ { - "EQ": { "value.person.org": "Finance" } + "EQ": { "person.org": "Finance" } }, { - "IN": { "value.state": [ "CA", "WA" ] } + "IN": { "state": [ "CA", "WA" ] } } ] } @@ -354,11 +372,11 @@ The pagination token is used "as is" in the [subsequent query](../query-api-exam }, "sort": [ { - "key": "value.state", + "key": "state", "order": "DESC" }, { - "key": "value.person.id" + "key": "person.id" } ], "page": { diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query1.json b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query1.json index ada5369e8..34c558aae 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query1.json +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query1.json @@ -1,10 +1,10 @@ { "filter": { - "EQ": { "value.state": "CA" } + "EQ": { "state": "CA" } }, "sort": [ { - "key": "value.person.id", + "key": "person.id", "order": "DESC" } ] diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query2.json b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query2.json index e66e566c2..0f8e1e9ad 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query2.json +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query2.json @@ -1,5 +1,5 @@ { "filter": { - "IN": { "value.person.org": [ "Dev Ops", "Hardware" ] } + "IN": { "person.org": [ "Dev Ops", "Hardware" ] } } } diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3-token.json b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3-token.json index 87a2e5582..61c21c3de 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3-token.json +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3-token.json @@ -2,15 +2,15 @@ "filter": { "OR": [ { - "EQ": { "value.person.org": "Dev Ops" } + "EQ": { "person.org": "Dev Ops" } }, { "AND": [ { - "EQ": { "value.person.org": "Finance" } + "EQ": { "person.org": "Finance" } }, { - "IN": { "value.state": [ "CA", "WA" ] } + "IN": { "state": [ "CA", "WA" ] } } ] } @@ -18,11 +18,11 @@ }, "sort": [ { - "key": "value.state", + "key": "state", "order": "DESC" }, { - "key": "value.person.id" + "key": "person.id" } ], "page": { diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3.json b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3.json index 5a8b7ff1c..e93f5bfdd 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3.json +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-api-examples/query3.json @@ -2,15 +2,15 @@ "filter": { "OR": [ { - "EQ": { "value.person.org": "Dev Ops" } + "EQ": { "person.org": "Dev Ops" } }, { "AND": [ { - "EQ": { "value.person.org": "Finance" } + "EQ": { "person.org": "Finance" } }, { - "IN": { "value.state": [ "CA", "WA" ] } + "IN": { "state": [ "CA", "WA" ] } } ] } @@ -18,11 +18,11 @@ }, "sort": [ { - "key": "value.state", + "key": "state", "order": "DESC" }, { - "key": "value.person.id" + "key": "person.id" } ], "page": { diff --git a/daprdocs/content/en/reference/api/state_api.md b/daprdocs/content/en/reference/api/state_api.md index 7068a92c3..68ce96369 100644 --- a/daprdocs/content/en/reference/api/state_api.md +++ b/daprdocs/content/en/reference/api/state_api.md @@ -336,15 +336,15 @@ curl http://localhost:3500/v1.0-alpha1/state/myStore/query \ "filter": { "OR": [ { - "EQ": { "value.person.org": "Dev Ops" } + "EQ": { "person.org": "Dev Ops" } }, { "AND": [ { - "EQ": { "value.person.org": "Finance" } + "EQ": { "person.org": "Finance" } }, { - "IN": { "value.state": [ "CA", "WA" ] } + "IN": { "state": [ "CA", "WA" ] } } ] } @@ -352,11 +352,11 @@ curl http://localhost:3500/v1.0-alpha1/state/myStore/query \ }, "sort": [ { - "key": "value.state", + "key": "state", "order": "DESC" }, { - "key": "value.person.id" + "key": "person.id" } ], "page": {