跳转到主要内容
新的 Search API 已发布针对 Chroma Cloud 数据库，功能强大的全新 Search API 现已支持密集向量搜索、混合搜索等功能。
Query API 支持对密集嵌入进行最近邻相似度搜索。如果您想检索记录而不进行相似度排序，请使用 Get API。

​
查询 (Query)

您可以使用 .query 对集合进行相似度搜索
collection.query(
    query_texts=["thus spake zarathustra", "the oracle speaks"]
)
Chroma 将使用集合的 嵌入函数 (embedding function) 对您的文本查询进行嵌入，并使用输出结果对您的集合运行向量相似度搜索。除了提供 query_texts，您也可以直接提供 query_embeddings。如果您的集合没有附加嵌入函数，则必须这样做。查询嵌入的维度必须与集合中嵌入的维度相匹配。Python 还支持 query_images 和 query_uris 作为查询输入。
collection.query(
    query_embeddings=[[11.1, 12.1, 13.1], [1.1, 2.3, 3.2]]
)
默认情况下，Chroma 会为每个输入查询返回 10 个结果。您可以使用 n_results 参数修改此数量
collection.query(
    query_embeddings=[[11.1, 12.1, 13.1], [1.1, 2.3, 3.2]],
    n_results=100
)
ids 参数允许您将搜索范围限制在所提供列表中的 ID 对应的记录内
collection.query(
    query_embeddings=[[11.1, 12.1, 13.1], [1.1, 2.3, 3.2]],
    n_results=100,
    ids=["id1", "id2"]
)
query 和 get 都支持用于 元数据过滤 的 where 参数，以及用于 全文搜索和正则 的 where_document 参数
collection.query(
    query_embeddings=[[11.1, 12.1, 13.1], [1.1, 2.3, 3.2]],
    n_results=100,
    where={"page": 10}, # query records with metadata field 'page' equal to 10
    where_document={"$contains": "search string"} # query records with the search string in the records' document
)

​
获取 (Get)

使用 .get 通过 ID 和/或过滤器检索记录，而不进行相似度排序
collection.get(ids=["id1", "id2"]) # by IDs

collection.get(limit=100, offset=0) # with pagination

​
结果形状

Chroma 以 列主序 (column-major) 形式（每个字段一个数组）返回 .query 和 .get 的结果。.query 结果按输入查询分组；.get 结果是记录的扁平列表。 
class QueryResult(TypedDict):
    ids: List[IDs]
    embeddings: Optional[List[Embeddings]]
    documents: Optional[List[List[Document]]]
    uris: Optional[List[List[URI]]]
    metadatas: Optional[List[List[Metadata]]]
    distances: Optional[List[List[float]]]
    included: Include

class GetResult(TypedDict):
    ids: List[ID]
    embeddings: Optional[Embeddings]
    documents: Optional[List[Document]]
    uris: Optional[URIs]
    metadatas: Optional[List[Metadata]]
    included: Include
在 Get 操作的结果中，每个数组中相对应的元素属于同一个文档。 
result = collection.get(include=["documents", "metadatas"])
for id, document, metadata in zip(result["ids"], result["documents"], result["metadatas"]):
    print(id, document, metadata)
Query 是一个批量 API，返回按输入分组的结果。常见的模式是遍历每个查询的“批次”结果，然后在该批次内进行遍历。 
result = collection.query(query_texts=["first query", "second query"])
for ids, documents, metadatas in zip(result["ids"], result["documents"], result["metadatas"]):
    for id, document, metadata in zip(ids, documents, metadatas):
        print(id, document, metadata)

​
选择返回哪些数据

默认情况下，Query 返回 documents、metadatas 和 distances，而 Get 返回 documents 和 metadatas。使用 include 参数来控制返回的内容。ids 总是会被返回。
collection.query(
    query_texts=["my query"],
    include=["documents", "metadatas", "embeddings"],
)

collection.get(include=["documents"])