文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云数据库 AI 服务>Memory 应用指南>开发者工具>Python SDK>Event 管理>查询 Event

查询 Event

最近更新时间：2026-02-05 12:30:01

我的收藏

本页目录：

接口定义

本接口query_events()用于查询会话中的事件。
按用户查询：通过 actor_id 查询特定用户的事件。
按会话查询：通过 session_id 查询特定会话中的事件。
灵活的条件查询：支持按时间范围、事件 ID、事件状态等多字段组合筛选，并提供比较操作符和集合操作符实现条件查询。
分页查询：使用 limit + offset 实现大量事件的分批加载。
def query_events(self,
                 actor_id: Optional[str] = None,
                 session_id: Optional[str] = None,
                 where: Optional[Dict[str, Any]] = None,
                 limit: Optional[int] = None,
                 offset: Optional[int] = None,
                 ) -> Dict[str, Any]:

使用示例

import json
events = client.query_events(
    where={
      "timestamp": {
        "$gte": "2025-12-01T10:00:00Z",
        "$lte": "2025-12-01T11:59:59Z"
      },
      "event_id": {
        "$in": ["event-56c31d95********", "event-e1824f59********"]
      },
      "status": "processed"
    },
    limit=2,
    offset=0
)
print(json.dumps(events, ensure_ascii=False))

入参描述

参数
是否必选
参数含义
配置方法及要求
actor_id
否
指定查询会话（Session）中所属用户的唯一标识 ID。
数据类型：String。
长度限制：[1,128]。
字符规则：任意字符。
session_id
否
指定查询事件的 Session ID。
获取会话 ID，请参见 查询 Session。
where
否
指定查询过滤匹配规则，通过键值对定义字段匹配规则，返回符合条件的事件记录。
支持设置查询条件的字段，如下所示：
timestamp：事件产生的时间。使用 ISO 8601 格式 `YYYY-MM-DDTHH:MM:SSZ`。
event_id：事件 ID。
status：事件状态，可选值如下所示。
pending：待处理，表示事件已进入队列，尚未开始处理。
processing：处理中，表示事件正在被系统执行。
failed：处理失败，表示事件在处理过程中发生错误。
processed：已处理，表示事件已成功完成。
支持使用的操作符：
比较操作符：$eq（等于，默认可省略）、$ne（不等于）、$gt（大于）、$gte（大于等于）、$lt（小于）、$lte（小于等于）。
集合操作符：$in（包含在数组中）、$nin（不包含在数组中）。
limit
否
指定返回的事件数量。
数据类型：Integer，正整数。
取值范围：1～1000。
默认值：10。
offset
否
指定返回结果列表的起始偏移量。
数据类型：Integer，正整数。
默认值：0，表示从数据集的第一条记录开始返回。
示例：offset=20 表示跳过前20条记录，从第21条开始返回。

出参描述

执行成功，输出如下信息。
{
  "memory_id": "tdai-mem-228j****",
  "events": [
    {
      "event_id": "event-56c31d95********",
      "actor_id": "user-service-test",
      "session_id": "session-e53171ad********",
      "status": "processed",
      "messages": {
        "role": "assistant",
        "content": "收到！考虑到您女朋友的喜好。这是为您和您女友定制的杭州三日行程：\\n\\n第一天：上午游茅家埠、杨公堤；下午观天目里美术馆现代展览。晚餐于胜利河美食街 品尝安全地道的本帮菜。\\n\\n第二天：上午早访灵隐寺，漫步幽静天竺路。下午重点参观 浙江省博物馆之江馆 重磅国际艺术大展。晚餐体验本地 新丰小吃（已规避风险）。\\n\\n第三天：上午于 西溪湿地乘摇橹船。下午在小河直街 咖啡馆悠闲小憩，结束旅程。",
        "timestamp": "2025-12-01T10:07:05.000Z"
      }
    },
    {
      "event_id": "event-e1824f59*********",
      "actor_id": "user-service-test",
      "session_id": "session-e53171ad********",
      "status": "processed",
      "messages": {
        "role": "user",
        "content": "完美！哦对了，我女朋友更喜欢现代艺术，有什么地方可以推荐吗？",
        "timestamp": "2025-12-01T10:06:05.000Z"
      }
    }
  ],
  "total_count": 8
}
参数名（一级）
数据类型
参数名（二级）
参数含义
events
List
event_id
返回满足条件的事件 ID。
actor_id
用户 ID。
session_id
Session 的唯一标识 ID。
messages
返回事件的消息对象。
status
事件状态。
pending：待处理，表示事件已进入队列，尚未开始处理。
processing：处理中，表示事件正在被系统执行。
failed：处理失败，表示事件在处理过程中发生错误。
processed：已处理，表示事件已成功完成。
total_count
Integer
-
符合条件的事件总数。
中国站