跳到内容

存储

持久化键值存储的基类和类型。

存储提供了可在线程和对话之间持久存在的长期记忆。支持分层命名空间、键值存储和可选的向量搜索。

核心类型
  • BaseStore:具有同步/异步操作的存储接口
  • Item:带有元数据的已存储键值对
  • Op:Get/Put/Search/List 操作

模块

名称 描述
batch

用于在后台任务中批量处理操作的实用程序。

embed

用于处理嵌入函数和 LangChain 的 Embeddings 接口的实用程序。

名称 描述
Embeddings

嵌入模型的接口。

表示一个带有元数据的存储项。

GetOp

通过其命名空间和键来检索特定项的操作。

SearchOp

在指定的命名空间层级中搜索项的操作。

MatchCondition

表示用于匹配存储中命名空间的模式。

ListNamespacesOp

列出和过滤存储中命名空间的操作。

PutOp

在存储中存储、更新或删除项的操作。

基础存储

用于持久化键值存储的抽象基类。

函数

名称 描述
ensure_embeddings

确保嵌入函数符合 LangChain 的 Embeddings 接口。

get_text_at_path

使用路径表达式或预分词的路径从对象中提取文本。

tokenize_path

将路径分词为组件。

属性

名称 类型 描述
NamespacePath

一个表示命名空间路径的元组,可以包含通配符。

NamespaceMatchType

指定如何匹配命名空间路径。

NamespacePath module-attribute

NamespacePath = tuple[Union[str, Literal['*']], ...]

一个表示命名空间路径的元组,可以包含通配符。

示例
("users",)  # Exact users namespace
("documents", "*")  # Any sub-namespace under documents
("cache", "*", "v1")  # Any cache category with v1 version

NamespaceMatchType module-attribute

NamespaceMatchType = Literal['prefix', 'suffix']

指定如何匹配命名空间路径。

"prefix":从命名空间的开头匹配 "suffix":从命名空间的末尾匹配

Embeddings

基类:ABC

嵌入模型的接口。

这是一个用于实现文本嵌入模型的接口。

文本嵌入模型用于将文本映射到一个向量(n 维空间中的一个点)。

相似的文本通常会被映射到该空间中彼此接近的点。具体什么是“相似”以及如何在该空间中测量“距离”的细节,取决于具体的嵌入模型。

此抽象包含一个用于嵌入文档列表的方法和一个用于嵌入查询文本的方法。查询文本的嵌入预期为单个向量,而文档列表的嵌入预期为向量列表。

通常,查询嵌入与文档嵌入相同,但该抽象允许独立处理它们。

除了同步方法,该接口还提供了方法的异步版本。

默认情况下,异步方法是使用同步方法实现的;但是,实现可以选择用异步原生实现来覆盖异步方法以提高性能。

方法

名称 描述
embed_documents

嵌入搜索文档。

embed_query

嵌入查询文本。

aembed_documents

异步嵌入搜索文档。

aembed_query

异步嵌入查询文本。

embed_documents abstractmethod

embed_documents(texts: list[str]) -> list[list[float]]

嵌入搜索文档。

参数

名称 类型 描述 默认值
texts list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

embed_query abstractmethod

embed_query(text: str) -> list[float]

嵌入查询文本。

参数

名称 类型 描述 默认值
text str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

aembed_documents async

aembed_documents(texts: list[str]) -> list[list[float]]

异步嵌入搜索文档。

参数

名称 类型 描述 默认值
texts list[str]

要嵌入的文本列表。

必填

返回

类型 描述
list[list[float]]

嵌入列表。

aembed_query async

aembed_query(text: str) -> list[float]

异步嵌入查询文本。

参数

名称 类型 描述 默认值
text str

要嵌入的文本。

必填

返回

类型 描述
list[float]

嵌入。

NotProvided

哨兵单例。

Item

表示一个带有元数据的存储项。

参数

名称 类型 描述 默认值
dict[str, Any]

以字典形式存储的数据。键是可过滤的。

必填
str

命名空间内的唯一标识符。

必填
namespace tuple[str, ...]

定义此文档所在集合的分层路径。表示为字符串元组,允许嵌套分类。例如:("documents", 'user123')

必填
创建时间 datetime

项创建的时间戳。

必填
updated_at datetime

最后更新的时间戳。

必填

SearchItem

基类:Item

表示从搜索操作返回的带有附加元数据的项。

方法

名称 描述
__init__

初始化一个结果项。

__init__

__init__(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    created_at: datetime,
    updated_at: datetime,
    score: float | None = None,
) -> None

初始化一个结果项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
dict[str, Any]

存储的值。

必填
创建时间 datetime

项首次创建的时间。

必填
updated_at datetime

项最后更新的时间。

必填
score float | None

如果来自排名操作,则为相关性/相似性得分。

None

GetOp

基类:NamedTuple

通过其命名空间和键来检索特定项的操作。

此操作允许使用其完整路径(命名空间)和唯一标识符(键)组合来精确检索存储的项。

示例

基本项检索

GetOp(namespace=("users", "profiles"), key="user123")
GetOp(namespace=("cache", "embeddings"), key="doc456")

属性

名称 类型 描述
namespace tuple[str, ...]

唯一标识项位置的分层路径。

str

项在其特定命名空间内的唯一标识符。

refresh_ttl bool

是否刷新返回项的 TTL。

namespace instance-attribute

namespace: tuple[str, ...]

唯一标识项位置的分层路径。

示例
("users",)  # Root level users namespace
("users", "profiles")  # Profiles within users namespace

key instance-attribute

key: str

项在其特定命名空间内的唯一标识符。

示例
"user123"  # For a user profile
"doc456"  # For a document

refresh_ttl class-attribute instance-attribute

refresh_ttl: bool = True

是否刷新返回项的 TTL。

如果没有为原始项指定 TTL,或者您的适配器未启用 TTL 支持,则此参数将被忽略。

SearchOp

基类:NamedTuple

在指定的命名空间层级中搜索项的操作。

此操作支持在给定的命名空间前缀内进行结构化筛选和自然语言搜索。它通过 limit 和 offset 参数提供分页功能。

注意

自然语言搜索支持取决于您的存储实现。

示例

带筛选和分页的搜索

SearchOp(
    namespace_prefix=("documents",),
    filter={"type": "report", "status": "active"},
    limit=5,
    offset=10
)

自然语言搜索

SearchOp(
    namespace_prefix=("users", "content"),
    query="technical documentation about APIs",
    limit=20
)

属性

名称 类型 描述
namespace_prefix tuple[str, ...]

定义搜索范围的分层路径前缀。

过滤器 dict[str, Any] | None

用于根据精确匹配或比较运算符筛选结果的键值对。

限制 整数

在搜索结果中返回的最大项数。

offset 整数

用于分页的要跳过的匹配项数。

查询 str | None

用于语义搜索功能的自然语言搜索查询。

refresh_ttl bool

是否刷新返回项的 TTL。

namespace_prefix instance-attribute

namespace_prefix: tuple[str, ...]

定义搜索范围的分层路径前缀。

示例
()  # Search entire store
("documents",)  # Search all documents
("users", "content")  # Search within user content

filter class-attribute instance-attribute

filter: dict[str, Any] | None = None

用于根据精确匹配或比较运算符筛选结果的键值对。

筛选器支持精确匹配和基于运算符的比较。

支持的运算符
  • $eq:等于(与直接值比较相同)
  • $ne:不等于
  • $gt:大于
  • $gte:大于或等于
  • $lt:小于
  • $lte:小于或等于
示例

简单精确匹配

{"status": "active"}

比较运算符

{"score": {"$gt": 4.99}}  # Score greater than 4.99

多个条件

{
    "score": {"$gte": 3.0},
    "color": "red"
}

limit class-attribute instance-attribute

limit: int = 10

在搜索结果中返回的最大项数。

offset class-attribute instance-attribute

offset: int = 0

用于分页的要跳过的匹配项数。

query class-attribute instance-attribute

query: str | None = None

用于语义搜索功能的自然语言搜索查询。

示例
  • "关于 REST API 的技术文档"
  • "2023 年的机器学习论文"

refresh_ttl class-attribute instance-attribute

refresh_ttl: bool = True

是否刷新返回项的 TTL。

如果没有为原始项指定 TTL,或者您的适配器未启用 TTL 支持,则此参数将被忽略。

MatchCondition

基类:NamedTuple

表示用于匹配存储中命名空间的模式。

此类将匹配类型(前缀或后缀)与可包含通配符的命名空间路径模式相结合,以灵活匹配不同的命名空间层级。

示例

前缀匹配

MatchCondition(match_type="prefix", path=("users", "profiles"))

带通配符的后缀匹配

MatchCondition(match_type="suffix", path=("cache", "*"))

简单后缀匹配

MatchCondition(match_type="suffix", path=("v1",))

属性

名称 类型 描述
match_type NamespaceMatchType

要执行的命名空间匹配类型。

path NamespacePath

可以包含通配符的命名空间路径模式。

match_type instance-attribute

match_type: NamespaceMatchType

要执行的命名空间匹配类型。

path instance-attribute

可以包含通配符的命名空间路径模式。

ListNamespacesOp

基类:NamedTuple

列出和过滤存储中命名空间的操作。

此操作允许探索数据组织、查找特定集合以及导航命名空间层级。

示例

列出“documents”路径下的所有命名空间

ListNamespacesOp(
    match_conditions=(MatchCondition(match_type="prefix", path=("documents",)),),
    max_depth=2
)

列出所有以“v1”结尾的命名空间

ListNamespacesOp(
    match_conditions=(MatchCondition(match_type="suffix", path=("v1",)),),
    limit=50
)

属性

名称 类型 描述
match_conditions tuple[MatchCondition, ...] | None

用于筛选命名空间的可选条件。

max_depth int | None

要返回的命名空间层级的最大深度。

限制 整数

要返回的最大命名空间数量。

offset 整数

用于分页的要跳过的命名空间数量。

match_conditions class-attribute instance-attribute

match_conditions: tuple[MatchCondition, ...] | None = None

用于筛选命名空间的可选条件。

示例

所有用户命名空间

(MatchCondition(match_type="prefix", path=("users",)),)

所有以“docs”开头并以“draft”结尾的命名空间

(
    MatchCondition(match_type="prefix", path=("docs",)),
    MatchCondition(match_type="suffix", path=("draft",))
) 

max_depth class-attribute instance-attribute

max_depth: int | None = None

要返回的命名空间层级的最大深度。

注意

比此级别更深的命名空间将被截断。

limit class-attribute instance-attribute

limit: int = 100

要返回的最大命名空间数量。

offset class-attribute instance-attribute

offset: int = 0

用于分页的要跳过的命名空间数量。

PutOp

基类:NamedTuple

在存储中存储、更新或删除项的操作。

此类表示一个修改存储内容的单一操作,无论是添加新项、更新现有项还是删除它们。

属性

名称 类型 描述
namespace tuple[str, ...]

标识项位置的分层路径。

str

项在其命名空间内的唯一标识符。

dict[str, Any] | None

要存储的数据,或为 None 以标记要删除的项。

index Literal[False] | list[str] | None

控制项的字段如何为搜索操作建立索引。

生存时间 float | None

控制项的 TTL(生存时间),以分钟为单位。

namespace instance-attribute

namespace: tuple[str, ...]

标识项位置的分层路径。

命名空间的作用类似于文件夹结构,用于组织项。元组中的每个元素代表层次结构中的一个级别。

示例

根级别文档

("documents",)

用户特定文档

("documents", "user123")

嵌套缓存结构

("cache", "embeddings", "v1")

key instance-attribute

key: str

项在其命名空间内的唯一标识符。

键在特定命名空间内必须是唯一的,以避免冲突。它与命名空间一起构成了项的完整路径。

示例

如果命名空间是 ("documents", "user123") 且键是 "report1",则完整路径实际上是 "documents/user123/report1"

value instance-attribute

value: dict[str, Any] | None

要存储的数据,或为 None 以标记要删除的项。

值必须是具有字符串键和 JSON 可序列化值的字典。将其设置为 None 表示该项应被删除。

示例

{ "field1": "string value", "field2": 123, "nested": {"can": "contain", "any": "serializable data"} }

index class-attribute instance-attribute

index: Literal[False] | list[str] | None = None

控制项的字段如何为搜索操作建立索引。

无论索引如何,该项仍然可以通过直接的 get() 操作访问。当被索引时,可以通过向量相似性搜索(如果存储实现支持)使用自然语言查询来搜索字段。

路径语法
  • 简单字段访问:"field"
  • 嵌套字段:"parent.child.grandchild"
  • 数组索引
  • 特定索引:"array[0]"
  • 最后一个元素:"array[-1]"
  • 所有元素(每个单独):"array[*]"
示例
  • None - 使用存储默认值(整个项)
  • list[str] - 要索引的字段列表
[
    "metadata.title",                    # Nested field access
    "context[*].content",                # Index content from all context as separate vectors
    "authors[0].name",                   # First author's name
    "revisions[-1].changes",             # Most recent revision's changes
    "sections[*].paragraphs[*].text",    # All text from all paragraphs in all sections
    "metadata.tags[*]",                  # All tags in metadata
]

ttl class-attribute instance-attribute

ttl: float | None = None

控制项的 TTL(生存时间),以分钟为单位。

如果提供,并且您使用的存储支持此功能,则该项将在最后一次访问后的这么多分钟后过期。过期计时器会在读取操作(get/search)和写入操作(put/update)时刷新。当 TTL 过期时,该项将被尽力安排删除。默认为 None(无过期)。

InvalidNamespaceError

基类:ValueError

提供的命名空间无效。

TTLConfig

基础类: TypedDict

存储中 TTL(生存时间)行为的配置。

属性

名称 类型 描述
refresh_on_read bool

在读取操作(GET 和 SEARCH)上刷新 TTL 的默认行为。

default_ttl float | None

新项的默认 TTL(生存时间),以分钟为单位。

sweep_interval_minutes int | None

TTL 清扫操作之间的间隔,以分钟为单位。

refresh_on_read instance-attribute

refresh_on_read: bool

在读取操作(GET 和 SEARCH)上刷新 TTL 的默认行为。

如果为 True,TTL 将在读取操作(get/search)时默认刷新。这可以通过显式设置 refresh_ttl 来为每个操作覆盖。如果未配置,则默认为 True。

default_ttl instance-attribute

default_ttl: float | None

新项的默认 TTL(生存时间),以分钟为单位。

如果提供,新项将在最后一次访问后这么多分钟后过期。过期计时器在读取和写入操作时都会刷新。默认为 None(无过期)。

sweep_interval_minutes instance-attribute

sweep_interval_minutes: int | None

TTL 清扫操作之间的间隔,以分钟为单位。

如果提供,存储将根据 TTL 定期删除过期的项。默认为 None(不进行清扫)。

IndexConfig

基础类: TypedDict

用于在存储中为语义搜索索引文档的配置。

如果未提供给存储,存储将不支持向量搜索。在这种情况下,所有对 put() 和 aput() 操作的 `index` 参数都将被忽略。

属性

名称 类型 描述
dims 整数

嵌入向量中的维度数。

embed Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str

用于从文本生成嵌入的可选函数。

fields list[str] | None

用于提取文本以生成嵌入的字段。

dims instance-attribute

dims: int

嵌入向量中的维度数。

常见的嵌入模型具有以下维度
  • openai:text-embedding-3-large: 3072
  • openai:text-embedding-3-small: 1536
  • openai:text-embedding-ada-002: 1536
  • cohere:embed-english-v3.0: 1024
  • cohere:embed-english-light-v3.0: 384
  • cohere:embed-multilingual-v3.0: 1024
  • cohere:embed-multilingual-light-v3.0: 384

embed instance-attribute

embed: Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str

用于从文本生成嵌入的可选函数。

可以通过三种方式指定
  1. 一个 LangChain Embeddings 实例
  2. 一个同步嵌入函数 (EmbeddingsFunc)
  3. 一个异步嵌入函数 (AEmbeddingsFunc)
  4. 一个提供商字符串(例如,"openai:text-embedding-3-small")
示例

使用 LangChain 的初始化与 InMemoryStore

from langchain.embeddings import init_embeddings
from langgraph.store.memory import InMemoryStore

store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": init_embeddings("openai:text-embedding-3-small")
    }
)

使用自定义嵌入函数与 InMemoryStore

from openai import OpenAI
from langgraph.store.memory import InMemoryStore

client = OpenAI()

def embed_texts(texts: list[str]) -> list[list[float]]:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [e.embedding for e in response.data]

store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": embed_texts
    }
)

使用异步嵌入函数与 InMemoryStore

from openai import AsyncOpenAI
from langgraph.store.memory import InMemoryStore

client = AsyncOpenAI()

async def aembed_texts(texts: list[str]) -> list[list[float]]:
    response = await client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [e.embedding for e in response.data]

store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": aembed_texts
    }
)

fields instance-attribute

fields: list[str] | None

用于提取文本以生成嵌入的字段。

控制存储项的哪些部分被嵌入以进行语义搜索。遵循 JSON 路径语法

- ["$"]: Embeds the entire JSON object as one vector  (default)
- ["field1", "field2"]: Embeds specific top-level fields
- ["parent.child"]: Embeds nested fields using dot notation
- ["array[*].field"]: Embeds field from each array element separately
注意

您始终可以在存储项时使用 `put` 或 `aput` 操作中的 `index` 参数来覆盖此行为。

示例
# Embed entire document (default)
fields=["$"]

# Embed specific fields
fields=["text", "summary"]

# Embed nested fields
fields=["metadata.title", "content.body"]

# Embed from arrays
fields=["messages[*].content"]  # Each message content separately
fields=["context[0].text"]      # First context item's text
注意
  • 文档中缺少的字段将被跳过
  • 数组表示法为每个元素创建单独的嵌入
  • 支持复杂的嵌套路径(例如,"a.b[*].c.d")

BaseStore

基类:ABC

用于持久化键值存储的抽象基类。

存储实现了持久性和内存,可以在线程之间共享,范围可以是用户 ID、助手 ID 或其他任意命名空间。某些实现可能通过可选的 `index` 配置支持语义搜索功能。

注意

语义搜索功能因实现而异,通常默认禁用。支持此功能的存储可以通过在创建时提供 `index` 配置来进行配置。如果没有此配置,语义搜索将被禁用,并且任何传递给存储操作的 `index` 参数都将无效。

同样,TTL(生存时间)支持默认是禁用的。子类必须显式设置 `supports_ttl = True` 来启用此功能。

方法

名称 描述
batch

在单个批处理中同步执行多个操作。

abatch

在单个批处理中异步执行多个操作。

获取

检索单个项。

search

在命名空间前缀内搜索项。

放置

在存储中存储或更新一个项目。

delete

删除项。

list_namespaces

在存储中列出和筛选命名空间。

异步获取

异步检索单个项。

asearch

在命名空间前缀内异步搜索项目。

aput

异步存储或更新一个项目。

adelete

异步删除一个项目。

alist_namespaces

异步地在存储中列出和筛选命名空间。

batch abstractmethod

batch(ops: Iterable[Op]) -> list[Result]

在单个批处理中同步执行多个操作。

参数

名称 类型 描述 默认值
ops Iterable[Op]

一个可迭代的要执行的操作。

必填

返回

类型 描述
list[Result]

一个结果列表,其中每个结果对应于输入中的一个操作。

list[Result]

结果的顺序与输入操作的顺序匹配。

abatch abstractmethod async

abatch(ops: Iterable[Op]) -> list[Result]

在单个批处理中异步执行多个操作。

参数

名称 类型 描述 默认值
ops Iterable[Op]

一个可迭代的要执行的操作。

必填

返回

类型 描述
list[Result]

一个结果列表,其中每个结果对应于输入中的一个操作。

list[Result]

结果的顺序与输入操作的顺序匹配。

get

get(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

检索单个项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
refresh_ttl bool | None

是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的默认 refresh_ttl 设置。如果未指定 TTL,则此参数将被忽略。

None

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

search

search(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: str | None = None,
    filter: dict[str, Any] | None = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: bool | None = None,
) -> list[SearchItem]

在命名空间前缀内搜索项。

参数

名称 类型 描述 默认值
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
查询 str | None

用于自然语言搜索的可选查询。

None
过滤器 dict[str, Any] | None

用于筛选结果的键值对。

None
限制 整数

返回的最大项数。

10
offset 整数

在返回结果之前跳过的项数。

0
refresh_ttl bool | None

是否刷新返回项的 TTL。如果未指定 TTL,此参数将被忽略。

None

返回

类型 描述
list[SearchItem]

匹配搜索条件的项列表。

示例

基本筛选

# Search for documents with specific metadata
results = store.search(
    ("docs",),
    filter={"type": "article", "status": "published"}
)

自然语言搜索(需要向量存储实现)

# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
    index={
        "dims": 1536,  # embedding dimensions
        "embed": your_embedding_function,  # function to create embeddings
        "fields": ["text"]  # fields to embed. Defaults to ["$"]
    }
)

# Search for semantically similar documents
results = store.search(
    ("docs",),
    query="machine learning applications in healthcare",
    filter={"type": "research_paper"},
    limit=5
)

注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。

put

put(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Literal[False] | list[str] | None = None,
    *,
    ttl: float | None | NotProvided = NOT_PROVIDED
) -> None

在存储中存储或更新一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Literal[False] | list[str] | None

控制项的字段如何为搜索建立索引

  • None(默认):使用您在创建存储时配置的 `fields`(如果有)。如果您未使用索引功能初始化存储,`index` 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
生存时间 float | None | NotProvided

生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。

同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

store.put(("docs",), "report", {"memory": "Will likes ai"})

不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=["memory"])

delete

delete(namespace: tuple[str, ...], key: str) -> None

删除项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

list_namespaces

list_namespaces(
    *,
    prefix: NamespacePath | None = None,
    suffix: NamespacePath | None = None,
    max_depth: int | None = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

在存储中列出和筛选命名空间。

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认值
prefix NamespacePath | None

筛选以此路径开头的命名空间。

None
suffix NamespacePath | None

筛选以此路径结尾的命名空间。

None
max_depth int | None

返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断。

None
限制 整数

要返回的最大命名空间数量(默认为 100)。

100
offset 整数

用于分页的要跳过的命名空间数量(默认为 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]:匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组代表一个完整的命名空间路径,直到 `max_depth`。

???+ 示例 "示例":设置 max_depth=3。给定命名空间

# Example if you have the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")
store.list_namespaces(prefix=("a", "b"), max_depth=3)
# [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

aget async

aget(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

异步检索单个项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

asearch async

asearch(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: str | None = None,
    filter: dict[str, Any] | None = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: bool | None = None,
) -> list[SearchItem]

在命名空间前缀内异步搜索项目。

参数

名称 类型 描述 默认值
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
查询 str | None

用于自然语言搜索的可选查询。

None
过滤器 dict[str, Any] | None

用于筛选结果的键值对。

None
限制 整数

返回的最大项数。

10
offset 整数

在返回结果之前跳过的项数。

0
refresh_ttl bool | None

是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的 TTLConfig.refresh_default 设置。如果未提供 TTLConfig 或未指定 TTL,则此参数将被忽略。

None

返回

类型 描述
list[SearchItem]

匹配搜索条件的项列表。

示例

基本筛选

# Search for documents with specific metadata
results = await store.asearch(
    ("docs",),
    filter={"type": "article", "status": "published"}
)

自然语言搜索(需要向量存储实现)

# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
    index={
        "dims": 1536,  # embedding dimensions
        "embed": your_embedding_function,  # function to create embeddings
        "fields": ["text"]  # fields to embed
    }
)

# Search for semantically similar documents
results = await store.asearch(
    ("docs",),
    query="machine learning applications in healthcare",
    filter={"type": "research_paper"},
    limit=5
)

注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。

aput async

aput(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Literal[False] | list[str] | None = None,
    *,
    ttl: float | None | NotProvided = NOT_PROVIDED
) -> None

异步存储或更新一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Literal[False] | list[str] | None

控制项的字段如何为搜索建立索引

  • None(默认):使用您在创建存储时配置的 `fields`(如果有)。如果您未使用索引功能初始化存储,`index` 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
生存时间 float | None | NotProvided

生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。

同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

await store.aput(("docs",), "report", {"memory": "Will likes ai"})

不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。

await store.aput(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段(如果存储配置为索引项)

await store.aput(
    ("docs",),
    "report",
    {
        "memory": "Will likes ai",
        "context": [{"content": "..."}, {"content": "..."}]
    },
    index=["memory", "context[*].content"]
)

adelete async

adelete(namespace: tuple[str, ...], key: str) -> None

异步删除一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

alist_namespaces async

alist_namespaces(
    *,
    prefix: NamespacePath | None = None,
    suffix: NamespacePath | None = None,
    max_depth: int | None = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

异步地在存储中列出和筛选命名空间。

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认值
prefix NamespacePath | None

筛选以此路径开头的命名空间。

None
suffix NamespacePath | None

筛选以此路径结尾的命名空间。

None
max_depth int | None

返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断至此深度。

None
限制 整数

要返回的最大命名空间数量(默认为 100)。

100
offset 整数

用于分页的要跳过的命名空间数量(默认为 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]:匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组代表一个完整的命名空间路径,直到 `max_depth`。

示例

在现有命名空间下设置 max_depth=3

# Given the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")

await store.alist_namespaces(prefix=("a", "b"), max_depth=3)
# Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

ensure_embeddings

ensure_embeddings(
    embed: (
        Embeddings
        | EmbeddingsFunc
        | AEmbeddingsFunc
        | str
        | None
    ),
) -> Embeddings

确保嵌入函数符合 LangChain 的 Embeddings 接口。

此函数包装任意嵌入函数,使其与 LangChain 的 Embeddings 接口兼容。它处理同步和异步函数。

参数

名称 类型 描述 默认值
embed Embeddings | EmbeddingsFunc | AEmbeddingsFunc | str | None

可以是现有的 Embeddings 实例,也可以是将文本转换为嵌入的函数。如果函数是异步的,它将用于同步和异步操作。

必填

返回

类型 描述
Embeddings

一个包装了所提供函数的 Embeddings 实例。

示例

包装一个同步嵌入函数

def my_embed_fn(texts):
    return [[0.1, 0.2] for _ in texts]

embeddings = ensure_embeddings(my_embed_fn)
result = embeddings.embed_query("hello")  # Returns [0.1, 0.2]

包装一个异步嵌入函数

async def my_async_fn(texts):
    return [[0.1, 0.2] for _ in texts]

embeddings = ensure_embeddings(my_async_fn)
result = await embeddings.aembed_query("hello")  # Returns [0.1, 0.2]

使用提供商字符串初始化嵌入

# Requires langchain>=0.3.9 and langgraph-checkpoint>=2.0.11
embeddings = ensure_embeddings("openai:text-embedding-3-small")
result = embeddings.embed_query("hello")

get_text_at_path

get_text_at_path(
    obj: Any, path: str | list[str]
) -> list[str]

使用路径表达式或预分词的路径从对象中提取文本。

参数

名称 类型 描述 默认值
obj Any

从中提取文本的对象

必填
path str | list[str]

路径字符串或预分词的路径列表。

必填

处理的路径类型

  • 简单路径:"field1.field2"
  • 数组索引:"[0]", "[*]", "[-1]"
  • 通配符:"*"
  • 多字段选择:"{field1,field2}"
  • 多字段中的嵌套路径:"{field1,nested.field2}"

tokenize_path

tokenize_path(path: str) -> list[str]

将路径分词为组件。

处理的类型

  • 简单路径:"field1.field2"
  • 数组索引:"[0]", "[*]", "[-1]"
  • 通配符:"*"
  • 多字段选择:"{field1,field2}"

模块

名称 描述
aio
base

名称 描述
AsyncPostgresStore

使用 pgvector 的异步 Postgres 支持的存储,可选向量搜索。

PostgresStore

使用 pgvector 的 Postgres 支持的存储,可选向量搜索。

AsyncPostgresStore

基类:AsyncBatchedBaseStore, BasePostgresStore[Conn]

使用 pgvector 的异步 Postgres 支持的存储,可选向量搜索。

示例

基本设置和用法

from langgraph.store.postgres import AsyncPostgresStore

conn_string = "postgresql://user:pass@localhost:5432/dbname"

async with AsyncPostgresStore.from_conn_string(conn_string) as store:
    await store.setup()  # Run migrations. Done once

    # Store and retrieve data
    await store.aput(("users", "123"), "prefs", {"theme": "dark"})
    item = await store.aget(("users", "123"), "prefs")

使用 LangChain 嵌入进行向量搜索

from langchain.embeddings import init_embeddings
from langgraph.store.postgres import AsyncPostgresStore

conn_string = "postgresql://user:pass@localhost:5432/dbname"

async with AsyncPostgresStore.from_conn_string(
    conn_string,
    index={
        "dims": 1536,
        "embed": init_embeddings("openai:text-embedding-3-small"),
        "fields": ["text"]  # specify which fields to embed. Default is the whole serialized value
    }
) as store:
    await store.setup()  # Run migrations. Done once

    # Store documents
    await store.aput(("docs",), "doc1", {"text": "Python tutorial"})
    await store.aput(("docs",), "doc2", {"text": "TypeScript guide"})
    await store.aput(("docs",), "doc3", {"text": "Other guide"}, index=False)  # don't index

    # Search by similarity
    results = await store.asearch(("docs",), query="programming guides", limit=2)

使用连接池以获得更好的性能

from langgraph.store.postgres import AsyncPostgresStore, PoolConfig

conn_string = "postgresql://user:pass@localhost:5432/dbname"

async with AsyncPostgresStore.from_conn_string(
    conn_string,
    pool_config=PoolConfig(
        min_size=5,
        max_size=20
    )
) as store:
    await store.setup()  # Run migrations. Done once
    # Use store with connection pooling...

警告

请确保:1. 在首次使用前调用 `setup()` 以创建必要的表和索引 2. pgvector 扩展可用以使用向量搜索 3. 使用 Python 3.10+ 以支持异步功能

注意

默认情况下,语义搜索是禁用的。您可以在创建存储时提供一个 `index` 配置来启用它。如果没有这个配置,所有传递给 `put` 或 `aput` 的 `index` 参数都将无效。

注意

如果您提供了 TTL 配置,则必须显式调用 `start_ttl_sweeper()` 来启动删除过期项的后台任务。在完成存储使用后,调用 `stop_ttl_sweeper()` 以正确清理资源。

方法

名称 描述
from_conn_string

从连接字符串创建一个新的 AsyncPostgresStore 实例。

setup

异步设置存储数据库。

sweep_ttl

根据 TTL 删除过期的存储项。

start_ttl_sweeper

根据 TTL 定期删除过期的存储项。

stop_ttl_sweeper

如果 TTL 清理器任务正在运行,则停止它。

from_conn_string async classmethod

from_conn_string(
    conn_string: str,
    *,
    pipeline: bool = False,
    pool_config: PoolConfig | None = None,
    index: PostgresIndexConfig | None = None,
    ttl: TTLConfig | None = None
) -> AsyncIterator[AsyncPostgresStore]

从连接字符串创建一个新的 AsyncPostgresStore 实例。

参数

名称 类型 描述 默认值
conn_string str

Postgres 连接信息字符串。

必填
pipeline bool

是否使用 AsyncPipeline(仅适用于单个连接)

False
pool_config PoolConfig | None

连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 `pipeline` 参数。

None
index PostgresIndexConfig | None

嵌入配置。

None

返回

名称 类型 描述
AsyncPostgresStore AsyncIterator[AsyncPostgresStore]

一个新的 AsyncPostgresStore 实例。

setup async

setup() -> None

异步设置存储数据库。

此方法在 Postgres 数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。用户在首次使用存储时必须直接调用此方法。

sweep_ttl async

sweep_ttl() -> int

根据 TTL 删除过期的存储项。

返回

名称 类型 描述
整数 整数

已删除项的数量。

start_ttl_sweeper async

start_ttl_sweeper(
    sweep_interval_minutes: int | None = None,
) -> Task[None]

根据 TTL 定期删除过期的存储项。

返回

类型 描述
Task[None]

可以等待或取消的任务。

stop_ttl_sweeper async

stop_ttl_sweeper(timeout: float | None = None) -> bool

如果 TTL 清理器任务正在运行,则停止它。

参数

名称 类型 描述 默认值
timeout float | None

等待任务停止的最长时间(秒)。如果为 None,则无限期等待。

None

返回

名称 类型 描述
bool bool

如果任务成功停止或未运行,则为 True;如果在任务停止前达到超时,则为 False。

PostgresStore

基类:BaseStore, BasePostgresStore[Conn]

使用 pgvector 的 Postgres 支持的存储,可选向量搜索。

示例

基本设置和用法

from langgraph.store.postgres import PostgresStore
from psycopg import Connection

conn_string = "postgresql://user:pass@localhost:5432/dbname"

# Using direct connection
with Connection.connect(conn_string) as conn:
    store = PostgresStore(conn)
    store.setup() # Run migrations. Done once

    # Store and retrieve data
    store.put(("users", "123"), "prefs", {"theme": "dark"})
    item = store.get(("users", "123"), "prefs")

或使用方便的 from_conn_string 辅助函数

from langgraph.store.postgres import PostgresStore

conn_string = "postgresql://user:pass@localhost:5432/dbname"

with PostgresStore.from_conn_string(conn_string) as store:
    store.setup()

    # Store and retrieve data
    store.put(("users", "123"), "prefs", {"theme": "dark"})
    item = store.get(("users", "123"), "prefs")

使用 LangChain 嵌入进行向量搜索

from langchain.embeddings import init_embeddings
from langgraph.store.postgres import PostgresStore

conn_string = "postgresql://user:pass@localhost:5432/dbname"

with PostgresStore.from_conn_string(
    conn_string,
    index={
        "dims": 1536,
        "embed": init_embeddings("openai:text-embedding-3-small"),
        "fields": ["text"]  # specify which fields to embed. Default is the whole serialized value
    }
) as store:
    store.setup() # Do this once to run migrations

    # Store documents
    store.put(("docs",), "doc1", {"text": "Python tutorial"})
    store.put(("docs",), "doc2", {"text": "TypeScript guide"})
    store.put(("docs",), "doc2", {"text": "Other guide"}, index=False) # don't index

    # Search by similarity
    results = store.search(("docs",), query="programming guides", limit=2)

注意

默认情况下,语义搜索是禁用的。您可以通过在创建存储时提供 `index` 配置来启用它。如果没有此配置,所有传递给 `put` 或 `aput` 的 `index` 参数都将无效。

警告

请确保在首次使用前调用 `setup()` 以创建必要的表和索引。必须有 pgvector 扩展才能使用向量搜索。

注意

如果您提供 TTL 配置,则必须显式调用 `start_ttl_sweeper()` 以启动删除过期项的后台线程。当您完成存储的使用时,请调用 `stop_ttl_sweeper()` 以正确清理资源。

方法

名称 描述
获取

检索单个项。

search

在命名空间前缀内搜索项。

放置

在存储中存储或更新一个项目。

delete

删除项。

list_namespaces

在存储中列出和筛选命名空间。

异步获取

异步检索单个项。

asearch

在命名空间前缀内异步搜索项目。

aput

异步存储或更新一个项目。

adelete

异步删除一个项目。

alist_namespaces

异步地在存储中列出和筛选命名空间。

from_conn_string

从连接字符串创建一个新的 PostgresStore 实例。

sweep_ttl

根据 TTL 删除过期的存储项。

start_ttl_sweeper

根据 TTL 定期删除过期的存储项。

stop_ttl_sweeper

如果 TTL 清理器线程正在运行,则停止它。

__del__

确保在对象被垃圾回收时停止 TTL 清理器线程。

setup

设置存储数据库。

get

get(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

检索单个项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填
refresh_ttl bool | None

是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的默认 refresh_ttl 设置。如果未指定 TTL,则此参数将被忽略。

None

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

search

search(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: str | None = None,
    filter: dict[str, Any] | None = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: bool | None = None,
) -> list[SearchItem]

在命名空间前缀内搜索项。

参数

名称 类型 描述 默认值
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
查询 str | None

用于自然语言搜索的可选查询。

None
过滤器 dict[str, Any] | None

用于筛选结果的键值对。

None
限制 整数

返回的最大项数。

10
offset 整数

在返回结果之前跳过的项数。

0
refresh_ttl bool | None

是否刷新返回项的 TTL。如果未指定 TTL,此参数将被忽略。

None

返回

类型 描述
list[SearchItem]

匹配搜索条件的项列表。

示例

基本筛选

# Search for documents with specific metadata
results = store.search(
    ("docs",),
    filter={"type": "article", "status": "published"}
)

自然语言搜索(需要向量存储实现)

# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
    index={
        "dims": 1536,  # embedding dimensions
        "embed": your_embedding_function,  # function to create embeddings
        "fields": ["text"]  # fields to embed. Defaults to ["$"]
    }
)

# Search for semantically similar documents
results = store.search(
    ("docs",),
    query="machine learning applications in healthcare",
    filter={"type": "research_paper"},
    limit=5
)

注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。

put

put(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Literal[False] | list[str] | None = None,
    *,
    ttl: float | None | NotProvided = NOT_PROVIDED
) -> None

在存储中存储或更新一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Literal[False] | list[str] | None

控制项的字段如何为搜索建立索引

  • None(默认):使用您在创建存储时配置的 `fields`(如果有)。如果您未使用索引功能初始化存储,`index` 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
生存时间 float | None | NotProvided

生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。

同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

store.put(("docs",), "report", {"memory": "Will likes ai"})

不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段。

store.put(("docs",), "report", {"memory": "Will likes ai"}, index=["memory"])

delete

delete(namespace: tuple[str, ...], key: str) -> None

删除项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

list_namespaces

list_namespaces(
    *,
    prefix: NamespacePath | None = None,
    suffix: NamespacePath | None = None,
    max_depth: int | None = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

在存储中列出和筛选命名空间。

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认值
prefix NamespacePath | None

筛选以此路径开头的命名空间。

None
suffix NamespacePath | None

筛选以此路径结尾的命名空间。

None
max_depth int | None

返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断。

None
限制 整数

要返回的最大命名空间数量(默认为 100)。

100
offset 整数

用于分页的要跳过的命名空间数量(默认为 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]:匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组代表一个完整的命名空间路径,直到 `max_depth`。

???+ 示例 "示例":设置 max_depth=3。给定命名空间

# Example if you have the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")
store.list_namespaces(prefix=("a", "b"), max_depth=3)
# [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

aget async

aget(
    namespace: tuple[str, ...],
    key: str,
    *,
    refresh_ttl: bool | None = None
) -> Item | None

异步检索单个项。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

返回

类型 描述
Item | None

检索到的项,如果未找到则为 None。

asearch async

asearch(
    namespace_prefix: tuple[str, ...],
    /,
    *,
    query: str | None = None,
    filter: dict[str, Any] | None = None,
    limit: int = 10,
    offset: int = 0,
    refresh_ttl: bool | None = None,
) -> list[SearchItem]

在命名空间前缀内异步搜索项目。

参数

名称 类型 描述 默认值
namespace_prefix tuple[str, ...]

要搜索的分层路径前缀。

必填
查询 str | None

用于自然语言搜索的可选查询。

None
过滤器 dict[str, Any] | None

用于筛选结果的键值对。

None
限制 整数

返回的最大项数。

10
offset 整数

在返回结果之前跳过的项数。

0
refresh_ttl bool | None

是否为返回的项刷新 TTL。如果为 None(默认),则使用存储的 TTLConfig.refresh_default 设置。如果未提供 TTLConfig 或未指定 TTL,则此参数将被忽略。

None

返回

类型 描述
list[SearchItem]

匹配搜索条件的项列表。

示例

基本筛选

# Search for documents with specific metadata
results = await store.asearch(
    ("docs",),
    filter={"type": "article", "status": "published"}
)

自然语言搜索(需要向量存储实现)

# Initialize store with embedding configuration
store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore
    index={
        "dims": 1536,  # embedding dimensions
        "embed": your_embedding_function,  # function to create embeddings
        "fields": ["text"]  # fields to embed
    }
)

# Search for semantically similar documents
results = await store.asearch(
    ("docs",),
    query="machine learning applications in healthcare",
    filter={"type": "research_paper"},
    limit=5
)

注意:自然语言搜索的支持取决于您的存储实现,并需要正确的嵌入配置。

aput async

aput(
    namespace: tuple[str, ...],
    key: str,
    value: dict[str, Any],
    index: Literal[False] | list[str] | None = None,
    *,
    ttl: float | None | NotProvided = NOT_PROVIDED
) -> None

异步存储或更新一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径,表示为字符串元组。示例:("documents", "user123")

必填
str

命名空间内的唯一标识符。与命名空间一起构成项的完整路径。

必填
dict[str, Any]

包含项数据的字典。必须包含字符串键和 JSON 可序列化的值。

必填
index Literal[False] | list[str] | None

控制项的字段如何为搜索建立索引

  • None(默认):使用您在创建存储时配置的 `fields`(如果有)。如果您未使用索引功能初始化存储,`index` 参数将被忽略
  • False:禁用此项的索引
  • list[str]:要索引的字段路径列表,支持
    • 嵌套字段:"metadata.title"
    • 数组访问:"chapters[*].content"(每个单独索引)
    • 特定索引:"authors[0].name"
None
生存时间 float | None | NotProvided

生存时间(以分钟为单位)。此参数的支持取决于您的存储适配器。如果指定,该项将在最后一次访问后的这么多分钟后过期。None 表示永不过期。过期的运行将择机删除。默认情况下,过期计时器在读取操作(get/search)和写入操作(put/update)时都会刷新,只要该项包含在操作中。

NOT_PROVIDED
注意

索引支持取决于您的存储实现。如果您没有使用索引功能初始化存储,`index` 参数将被忽略。

同样,TTL 支持取决于具体的存储实现。一些实现可能不支持项的过期。

示例

存储项。索引取决于您如何配置存储。

await store.aput(("docs",), "report", {"memory": "Will likes ai"})

不要为语义搜索索引项。仍然可以通过 get() 和 search() 操作访问,但不会有向量表示。

await store.aput(("docs",), "report", {"memory": "Will likes ai"}, index=False)

为搜索索引特定字段(如果存储配置为索引项)

await store.aput(
    ("docs",),
    "report",
    {
        "memory": "Will likes ai",
        "context": [{"content": "..."}, {"content": "..."}]
    },
    index=["memory", "context[*].content"]
)

adelete async

adelete(namespace: tuple[str, ...], key: str) -> None

异步删除一个项目。

参数

名称 类型 描述 默认值
namespace tuple[str, ...]

项的分层路径。

必填
str

命名空间内的唯一标识符。

必填

alist_namespaces async

alist_namespaces(
    *,
    prefix: NamespacePath | None = None,
    suffix: NamespacePath | None = None,
    max_depth: int | None = None,
    limit: int = 100,
    offset: int = 0
) -> list[tuple[str, ...]]

异步地在存储中列出和筛选命名空间。

用于探索数据组织、查找特定集合或导航命名空间层次结构。

参数

名称 类型 描述 默认值
prefix NamespacePath | None

筛选以此路径开头的命名空间。

None
suffix NamespacePath | None

筛选以此路径结尾的命名空间。

None
max_depth int | None

返回层次结构中此深度以下的命名空间。比此级别更深的命名空间将被截断至此深度。

None
限制 整数

要返回的最大命名空间数量(默认为 100)。

100
offset 整数

用于分页的要跳过的命名空间数量(默认为 0)。

0

返回

类型 描述
list[tuple[str, ...]]

List[Tuple[str, ...]]:匹配条件的命名空间元组列表。

list[tuple[str, ...]]

每个元组代表一个完整的命名空间路径,直到 `max_depth`。

示例

在现有命名空间下设置 max_depth=3

# Given the following namespaces:
# ("a", "b", "c")
# ("a", "b", "d", "e")
# ("a", "b", "d", "i")
# ("a", "b", "f")
# ("a", "c", "f")

await store.alist_namespaces(prefix=("a", "b"), max_depth=3)
# Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]

from_conn_string classmethod

from_conn_string(
    conn_string: str,
    *,
    pipeline: bool = False,
    pool_config: PoolConfig | None = None,
    index: PostgresIndexConfig | None = None,
    ttl: TTLConfig | None = None
) -> Iterator[PostgresStore]

从连接字符串创建一个新的 PostgresStore 实例。

参数

名称 类型 描述 默认值
conn_string str

Postgres 连接信息字符串。

必填
pipeline bool

是否使用 Pipeline

False
pool_config PoolConfig | None

连接池的配置。如果提供,将创建一个连接池并使用它而不是单个连接。这将覆盖 `pipeline` 参数。

None
index PostgresIndexConfig | None

存储的索引配置。

None
生存时间 TTLConfig | None

存储的 TTL 配置。

None

返回

名称 类型 描述
PostgresStore Iterator[PostgresStore]

一个新的 PostgresStore 实例。

sweep_ttl

sweep_ttl() -> int

根据 TTL 删除过期的存储项。

返回

名称 类型 描述
整数 整数

已删除项的数量。

start_ttl_sweeper

start_ttl_sweeper(
    sweep_interval_minutes: int | None = None,
) -> Future[None]

根据 TTL 定期删除过期的存储项。

返回

类型 描述
Future[None]

可以等待或取消的 Future。

stop_ttl_sweeper

stop_ttl_sweeper(timeout: float | None = None) -> bool

如果 TTL 清理器线程正在运行,则停止它。

参数

名称 类型 描述 默认值
timeout float | None

等待线程停止的最长时间(秒)。如果为 None,则无限期等待。

None

返回

名称 类型 描述
bool bool

如果线程成功停止或未运行,则为 True;如果在线程停止前达到超时,则为 False。

__del__

__del__() -> None

确保在对象被垃圾回收时停止 TTL 清理器线程。

setup

setup() -> None

设置存储数据库。

此方法在 Postgres 数据库中创建必要的表(如果它们尚不存在)并运行数据库迁移。用户在首次使用存储时必须直接调用此方法。