List data - LambdaDB Documentation

This page shows you how to use the list endpoint to list documents in a collection. Use this when you need to iterate over documents (for example, to export or scan) without running a ranked search.

Parameter	Description	Type	Default
size	Max number of documents to return per page (1–100).	integer	100
pageToken	Token for the next page of results.	string
includeVectors	Indicates whether vector values are included in the response.	boolean	false

from lambdadb import LambdaDB

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    coll = client.collection("my_collection")
    # List first page of documents
    res = coll.docs.list(size=10)
    # `res.docs` contains items (each item includes `doc` and metadata).
    # `res.documents` contains document bodies only.
    for item in res.docs:
        print(item)

    # List next page using the token from the previous response
    if res.next_page_token:
        res_next = coll.docs.list(size=10, page_token=res.next_page_token)

Python: LambdaDB supports context manager usage. __enter__ returns the client, and __exit__ calls client.close() (closing the SDK-owned HTTP client) and makes the client unusable after the with block. If you don’t use with, call client.close() when you’re done. If you pass a custom client=/async_client=, you own closing it.

import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});
const collection = client.collection("my_collection");

// List first page
const res = await collection.docs.list({ size: 20 });
console.log(res.docs?.length, res.total);

// List next page
if (res.nextPageToken) {
  const resNext = await collection.docs.list({
    size: 20,
    pageToken: res.nextPageToken,
  });
}

package main

import (
  "context"
  "log"
  lambdadb "github.com/lambdadb/go-lambdadb"
)

func main() {
  ctx := context.Background()
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )
  coll := client.Collection("my_collection")

  // List first page
  res, err := coll.Docs().List(ctx, &lambdadb.ListDocsOpts{Size: lambdadb.Int64(10)})
  if err != nil {
    log.Fatal(err)
  }
  for _, d := range res.Docs {
    _ = d
  }

  // List next page
  if res.NextPageToken != nil {
    resNext, _ := coll.Docs().List(ctx, &lambdadb.ListDocsOpts{
      Size:      lambdadb.Int64(10),
      PageToken: res.NextPageToken,
    })
    _ = resNext
  }
}

# List first page ($BASE_URL and $PROJECT_NAME match SDK base_url / project_name)
curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10" \
  -H "x-api-key: ${YOUR_API_KEY}"

# Include vector values when needed
curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10&includeVectors=true" \
  -H "x-api-key: ${YOUR_API_KEY}"

# List next page (use nextPageToken from previous response)
curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10&pageToken=YOUR_PAGE_TOKEN" \
  -H "x-api-key: ${YOUR_API_KEY}"

The response includes the total count, the current page of documents, and an optional token for the next page:

{
  "total": 2,
  "docs": [
    {
      "collection": "example-collection-name",
      "doc": {
        "id": "doc-1",
        "title": "Example document 1",
        "category": "docs"
      }
    },
    {
      "collection": "example-collection-name",
      "doc": {
        "id": "doc-2",
        "title": "Example document 2",
        "category": "docs"
      }
    }
  ],
  "nextPageToken": "eyJpZCI6ICJhYmMiLCAiY3JlYXRlZF9hdCI6ICIyMDI0LTExLTA1VDE0OjI3OjU2KzAwOjAwIn0=",
  "isDocsInline": true
}

Extended list request

For filtering, partition filtering, field selection, or a JSON request body, use the extended list endpoint:

from lambdadb import LambdaDB

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    coll = client.collection("my_collection")

    res = coll.docs.list(
        size=10,
        filter_={"queryString": {"query": "category:docs"}},
        partition_filter={"field": "tenant", "in": ["acme"]},
        fields={"include": ["id", "title", "category"]},
        include_vectors=False,
    )

import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});

const res = await client.collection("my_collection").docs.list({
  size: 10,
  filter: { queryString: { query: "category:docs" } },
  partitionFilter: { field: "tenant", in: ["acme"] },
  fields: { include: ["id", "title", "category"] },
  includeVectors: false,
});

package main

import (
  "context"
  "log"

  lambdadb "github.com/lambdadb/go-lambdadb"
  "github.com/lambdadb/go-lambdadb/models/components"
)

func main() {
  ctx := context.Background()
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )

  fields := components.CreateFieldsSelectorUnionFieldsSelector1(components.FieldsSelector1{
    Include: []string{"id", "title", "category"},
  })

  res, err := client.Collection("my_collection").Docs().List(ctx, &lambdadb.ListDocsOpts{
    Size: lambdadb.Int64(10),
    Filter: map[string]any{
      "queryString": map[string]any{"query": "category:docs"},
    },
    PartitionFilter: &components.PartitionFilter{
      Field: "tenant",
      In:    []string{"acme"},
    },
    Fields:         &fields,
    IncludeVectors: lambdadb.Bool(false),
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = res
}

curl -X POST "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs/list" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${YOUR_API_KEY}" \
  --data '{
    "size": 10,
    "filter": {
      "queryString": {
        "query": "category:docs"
      }
    },
    "partitionFilter": {
      "field": "tenant",
      "in": ["acme"]
    },
    "fields": {
      "include": ["id", "title", "category"]
    },
    "includeVectors": false
  }'

The SDK scoped list helpers (docs.list in Python and TypeScript, Docs().List in Go) use the extended list request automatically when you pass filter, partition filter, or field-selection options. In Go, pass these as Filter, PartitionFilter, Fields, and IncludeVectors on lambdadb.ListDocsOpts. The extended list request body supports:

Parameter	Description	Type	Default
size	Max number of documents to return per page (1–100).	integer	100
pageToken	Token for the next page of results.	string
filter	Filter applied before pagination. Supports `queryString` and nested `bool` filters.	object
partitionFilter	Restricts the request to matching partition values.	object
fields	Field selector with `include` and/or `exclude`. Use dot notation for nested fields.	object
includeVectors	Indicates whether vector values are included in the response.	boolean	false

filter uses the same queryString and bool shapes as the query API. List filters do not run vector or ranking queries. Use partitionFilter only for collections configured with a partition field. Inside a bool filter, occur can be filter, must, must_not, or should; when omitted, it defaults to should.

{
  "filter": {
    "bool": [
      {
        "queryString": {
          "query": "category:docs"
        },
        "occur": "filter"
      },
      {
        "queryString": {
          "query": "title:LambdaDB"
        },
        "occur": "must"
      }
    ]
  }
}

When you use nextPageToken with the extended endpoint, keep the same filter, partitionFilter, fields, and includeVectors options across pages.

To fetch specific documents by ID, use the fetch endpoint. To run ranked text, vector, sparse-vector, or hybrid search, use the query API.

​Extended list request

Extended list request