The documentation you are viewing is for Dapr v1.13 which is an older version of Dapr. For up-to-date documentation, see the latest version.

操作方法：查询状态

使用查询API查询状态存储

alpha

状态查询API目前处于alpha阶段。

使用状态查询 API，您可以检索、过滤和排序存储在状态存储组件中的键/值数据。查询 API 不能替代完整的查询语言。

即使状态存储是键/值存储，value 也可能是具有自己的层次结构、键和值的 JSON 文档。查询 API 允许您使用这些键和值来检索相应的文档。

查询状态

您可以通过 HTTP POST/PUT 或 gRPC 提交查询请求。请求的正文是包含 3 个条目的 JSON 映射:

filter
sort
page

`filter`

filter 指定查询条件的形式，其中每个节点代表一元或多元操作。

支持以下操作：

运算符	操作数	说明
`EQ`	key:value	key == value
`NEQ`	key:value	key != value
`GT`	key:value	key > value
`GTE`	key:value	key >= value
`LT`	key:value	key < value
`LTE`	key:value	key <= value
`IN`	key:[]value	key == value[0] OR key == value[1] OR … OR key == value[n]
`AND`	[]operation	operation[0] AND operation[1] AND … AND operation[n]
`OR`	[]operation	operation[0] OR operation[1] OR … OR operation[n]

操作数中的key与JSONPath表示法类似。键中的每个点表示一个嵌套的JSON结构。例如，考虑这个结构：

{
  "shape": {
    "name": "rectangle",
    "dimensions": {
      "height": 24,
      "width": 10
    },
    "color": {
      "name": "red",
      "code": "#FF0000"
    }
  }
}

要比较颜色代码的值，键将是shape.color.code。

如果省略filter部分，则查询将返回所有条目。

`sort`

sort 是一个有序数组，其中包含 key:order 对，其中:

key是状态存储中的键
order是一个可选字符串，表示排序顺序：
- "ASC"表示升序
- "DESC"用于降序排列如果省略，则默认为升序。

`page`

page 包含 limit 和 token 参数。

limit设置页面大小。
token是组件返回的迭代令牌，用于后续查询。

在后台，此查询请求被转换为本机查询语言，并由状态存储组件执行。

示例数据和查询

让我们看一些真实例子，从简单到复杂。

作为数据集，考虑一个包含员工记录的集合，包含员工ID、组织、州和城市。请注意，此数据集是一个键/值对数组，其中：

key 是唯一的 ID
value 是具有员工记录的 JSON 对象。

为了更好地说明功能，组织名称（org）和员工ID（id）作为嵌套的JSON人员对象。

首先，您需要创建 MongoDB 的实例，这是您的状态存储。

docker run -d --rm -p 27017:27017 --name mongodb mongo:5

接下来，启动一个 Dapr 应用程序。请参阅组件配置文件，它指示Dapr使用MongoDB作为其状态存储。

dapr run --app-id demo --dapr-http-port 3500 --resources-path query-api-examples/components/mongodb

使用员工数据集填充状态存储，以便以后可以查询它。

curl -X POST -H "Content-Type: application/json" -d @query-api-examples/dataset.json http://localhost:3500/v1.0/state/statestore

填充后，可以检查状态存储中的数据。在下面的图像中，MongoDB UI的一部分显示员工记录。

每个条目都有 _id 成员作为串联的对象键，value 包含 JSON 记录的成员。

查询 API 允许您从此 JSON 结构中选择记录。

现在，您可以运行示例查询。

示例 1

首先，找到加利福尼亚州的所有员工，并按其员工 ID 降序排序。

这是查询：

{
    "filter": {
        "EQ": { "state": "CA" }
    },
    "sort": [
        {
            "key": "person.id",
            "order": "DESC"
        }
    ]
}

在 SQL 中，此查询的等效项是：

SELECT * FROM c WHERE
  state = "CA"
ORDER BY
  person.id DESC

使用以下命令执行查询：

HTTP API (Bash)
HTTP API (PowerShell)

curl -s -X POST -H "Content-Type: application/json" -d @query-api-examples/query1.json http://localhost:3500/v1.0-alpha1/state/statestore/query | jq .

Invoke-RestMethod -Method Post -ContentType 'application/json' -InFile query-api-examples/query1.json -Uri 'http://localhost:3500/v1.0-alpha1/state/statestore/query'

查询结果是按请求的顺序排列的匹配键/值对的数组：

{
  "results": [
    {
      "key": "3",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1071
        },
        "city": "Sacramento",
        "state": "CA"
      },
      "etag": "44723d41-deb1-4c23-940e-3e6896c3b6f7"
    },
    {
      "key": "7",
      "data": {
        "city": "San Francisco",
        "state": "CA",
        "person": {
          "id": 1015,
          "org": "Dev Ops"
        }
      },
      "etag": "0e69e69f-3dbc-423a-9db8-26767fcd2220"
    },
    {
      "key": "5",
      "data": {
        "state": "CA",
        "person": {
          "org": "Hardware",
          "id": 1007
        },
        "city": "Los Angeles"
      },
      "etag": "f87478fa-e5c5-4be0-afa5-f9f9d75713d8"
    },
    {
      "key": "9",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1002
        },
        "city": "San Diego",
        "state": "CA"
      },
      "etag": "f5cf05cd-fb43-4154-a2ec-445c66d5f2f8"
    }
  ]
}

示例 2

现在，让我们查找"Dev Ops"和"Hardware"组织中的所有员工。

这是查询：

{
    "filter": {
        "IN": { "person.org": [ "Dev Ops", "Hardware" ] }
    }
}

在 SQL 中，此查询的等效项是：

SELECT * FROM c WHERE
  person.org IN ("Dev Ops", "Hardware")

使用以下命令执行查询：

HTTP API (Bash)
HTTP API (PowerShell)

curl -s -X POST -H "Content-Type: application/json" -d @query-api-examples/query2.json http://localhost:3500/v1.0-alpha1/state/statestore/query | jq .

Invoke-RestMethod -Method Post -ContentType 'application/json' -InFile query-api-examples/query2.json -Uri 'http://localhost:3500/v1.0-alpha1/state/statestore/query'

与前面的示例类似，结果是一个匹配键/值对的数组。

示例 3

在这个示例中，查找：

“Dev Ops” 部门的所有员工。
来自“Finance”部门的员工居住在华盛顿州和加利福尼亚州。

此外，让我们先按州（按字母降序）对结果进行排序，然后按员工 ID（升序）对结果进行排序。另外，让我们一次最多处理 3 条记录。

这是查询：

{
    "filter": {
        "OR": [
            {
                "EQ": { "person.org": "Dev Ops" }
            },
            {
                "AND": [
                    {
                        "EQ": { "person.org": "Finance" }
                    },
                    {
                        "IN": { "state": [ "CA", "WA" ] }
                    }
                ]
            }
        ]
    },
    "sort": [
        {
            "key": "state",
            "order": "DESC"
        },
        {
            "key": "person.id"
        }
    ],
    "page": {
        "limit": 3
    }
}

在 SQL 中，此查询的等效项是：

SELECT * FROM c WHERE
  person.org = "Dev Ops" OR
  (person.org = "Finance" AND state IN ("CA", "WA"))
ORDER BY
  state DESC,
  person.id ASC
LIMIT 3

使用以下命令执行查询：

HTTP API (Bash)
HTTP API (PowerShell)

curl -s -X POST -H "Content-Type: application/json" -d @query-api-examples/query3.json http://localhost:3500/v1.0-alpha1/state/statestore/query | jq .

Invoke-RestMethod -Method Post -ContentType 'application/json' -InFile query-api-examples/query3.json -Uri 'http://localhost:3500/v1.0-alpha1/state/statestore/query'

成功执行后，状态存储将返回一个 JSON 对象，其中包含匹配记录列表和分页标记：

{
  "results": [
    {
      "key": "1",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1036
        },
        "city": "Seattle",
        "state": "WA"
      },
      "etag": "6f54ad94-dfb9-46f0-a371-e42d550adb7d"
    },
    {
      "key": "4",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1042
        },
        "city": "Spokane",
        "state": "WA"
      },
      "etag": "7415707b-82ce-44d0-bf15-6dc6305af3b1"
    },
    {
      "key": "10",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1054
        },
        "city": "New York",
        "state": "NY"
      },
      "etag": "26bbba88-9461-48d1-8a35-db07c374e5aa"
    }
  ],
  "token": "3"
}

分页标记在subsequent query中"按原样"使用，以获取下一批记录：

{
    "filter": {
        "OR": [
            {
                "EQ": { "person.org": "Dev Ops" }
            },
            {
                "AND": [
                    {
                        "EQ": { "person.org": "Finance" }
                    },
                    {
                        "IN": { "state": [ "CA", "WA" ] }
                    }
                ]
            }
        ]
    },
    "sort": [
        {
            "key": "state",
            "order": "DESC"
        },
        {
            "key": "person.id"
        }
    ],
    "page": {
        "limit": 3,
        "token": "3"
    }
}

HTTP API (Bash)
HTTP API (PowerShell)

curl -s -X POST -H "Content-Type: application/json" -d @query-api-examples/query3-token.json http://localhost:3500/v1.0-alpha1/state/statestore/query | jq .

Invoke-RestMethod -Method Post -ContentType 'application/json' -InFile query-api-examples/query3-token.json -Uri 'http://localhost:3500/v1.0-alpha1/state/statestore/query'

此查询的结果是：

{
  "results": [
    {
      "key": "9",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1002
        },
        "city": "San Diego",
        "state": "CA"
      },
      "etag": "f5cf05cd-fb43-4154-a2ec-445c66d5f2f8"
    },
    {
      "key": "7",
      "data": {
        "city": "San Francisco",
        "state": "CA",
        "person": {
          "id": 1015,
          "org": "Dev Ops"
        }
      },
      "etag": "0e69e69f-3dbc-423a-9db8-26767fcd2220"
    },
    {
      "key": "3",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1071
        },
        "city": "Sacramento",
        "state": "CA"
      },
      "etag": "44723d41-deb1-4c23-940e-3e6896c3b6f7"
    }
  ],
  "token": "6"
}

这样，您可以更新查询中的分页令牌并循环访问结果，直到不再返回任何记录。

局限性

状态查询 API 具有以下限制：

要查询存储在状态存储中的 actor 状态，您需要对特定数据库使用查询 API。参见查询 actor 状态。
该 API 不适用于 Dapr 加密状态存储功能。由于加密是由 Dapr 运行时完成并存储为加密数据，因此这有效地阻止了服务器端查询。

您可以在相关链接部分找到更多信息。

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.