Data

Data stores JSON entries in named collections that belong to the agent and retrieves them by id, by a Lua Query filter, or by semantic search over an entry’s searchText. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. For one record per end user, use User instead. Verified against lua-cli 3.33.0.

import { Data } from 'lua-cli';

Quick example

import { Data } from 'lua-cli';

const entry = await Data.create('movies', { title: 'Inception', year: 2010 }, 'Inception Nolan sci-fi thriller');
const results = await Data.search('movies', 'mind-bending thriller', 5, 0.7);
const recent = await Data.get('movies', { year: { $gte: 2020 } }, 1, 20);

Methods

collections()

Lists the agent’s collections with entry counts, timestamps, and the status of any declared indexes.

Data.collections(): Promise<CustomDataCollectionsResponse>

Returns

CustomDataCollectionInfo[]

One entry per collection.

Show properties

string

Collection name.

number

Number of entries.

number

Unix time in milliseconds of the newest write.

number

Unix time in milliseconds of the oldest entry.

CustomDataIndexStatus[]

Present when the agent declared indexes: fields, status (pending, building, ready, failed, or rejected), error on failed and rejected, lastDeclaredAt, and lastUsedAt.

number

Number of collections.

Example

import { Data } from 'lua-cli';

const { data: collections } = await Data.collections();
for (const collection of collections) {
  for (const index of collection.indexes ?? []) {
    console.log(collection.name, index.fields, index.status, index.error ?? '');
  }
}

Errors — Failed to list custom data collections.

Available in deployed agents and in lua test. Until September 27, 2026 the deployed runtime lacked collections() and failed with Data.collections is not a function.

create()

Creates an entry and, when searchText is given, indexes it for search().

Data.create(
  collectionName: string,
  data: Record<string, any>,
  optionsOrSearchText?: string | CreateCustomDataOptions
): Promise<DataEntryInstance>

string

required

Collection name, for example movies.

Record<string, any>

required

Any JSON-serializable object.

string | { searchText?: string; index?: Array<string | string[]> }

A string sets searchText, the text search() embeds; include every term you expect queries to use. An object also accepts index: the data fields this agent filters on, each a single path ('businessId') or a compound of two paths (['country', 'businessId']). Declare indexes on every write; the platform builds them asynchronously and removes an index 14 days after its last declaration or matching filtered read. A compound index serves filters on its leftmost field alone or on both fields. Over-limit or invalid declarations are rejected and reported in collections(), never trimmed.

Returns

DataEntryInstance

The stored entry. Fields of data are readable directly (entry.title) and through entry.data.

Show properties

string

Entry id, for example entry_abc123.

string

The collection the entry belongs to.

Record<string, any>

The stored object.

Example

import { Data } from 'lua-cli';

const ticket = await Data.create('tickets', { subject: 'Login fails', status: 'open', accountId: 'acct_abc123' }, 'login fails password reset');
console.log(ticket.id, ticket.subject);

Errors — Failed to create custom data entry when the platform rejects the write.

Both forms work in deployed agents and in lua test: a string, or { searchText, index }. Until September 27, 2026 the deployed runtime rejected the object with searchText must be a string and never forwarded index; code written around that can move to the object form.

get()

Returns one page of entries that match a filter.

Data.get(collectionName: string, filter?: LuaQuery, page?: number, limit?: number): Promise<GetCustomDataResponse>

string

required

Collection to read.

LuaQuery

Matches fields of each entry’s data. Grammar, operators, and limits are on the Lua Query page. Omit it to page through everything.

number

default:1

Page number, starting at 1.

number

default:10

Entries per page. The maximum is 100.

Returns

CustomDataEntry[]

Plain entries, not DataEntryInstance objects: read fields through entry.data.

Show properties

string

Entry id.

Record<string, any>

The stored object.

number

Unix time in milliseconds.

number

Unix time in milliseconds.

string

The indexed text, when set.

Pagination

currentPage, totalPages, totalCount, limit, hasNextPage, hasPrevPage, nextPage (number or null), and prevPage (number or null).

Example

import { Data } from 'lua-cli';

const page = await Data.get('tickets', { status: 'open', accountId: 'acct_abc123' }, 1, 50);
const subjects = page.data.map((entry) => entry.data.subject);
console.log(subjects, page.pagination.totalCount);

Errors — an invalid filter is rejected with a FILTER_* code (see Lua Query errors). A filter on an undeclared field of a large collection fails with an error that names the field and the index declaration to add.

getEntry()

Returns one entry by id.

Data.getEntry(collectionName: string, entryId: string): Promise<DataEntryInstance>

string

required

Collection to read.

string

required

The entry’s id.

Returns — the entry as a DataEntryInstance. Example

import { Data } from 'lua-cli';

const ticket = await Data.getEntry('tickets', 'entry_abc123');
console.log(ticket.subject, ticket.data.status);

Errors — Failed to get custom data entry when no entry has that id.

update()

Merges fields into an entry and optionally replaces its searchText.

Data.update(
  collectionName: string,
  entryId: string,
  data: Record<string, any>,
  optionsOrSearchText?: string | CreateCustomDataOptions
): Promise<UpdateCustomDataResponse>

string

required

Collection that holds the entry.

string

required

The entry’s id.

Record<string, any>

required

Fields to add or replace. Other fields are kept.

string | { searchText?: string; index?: Array<string | string[]> }

As on create(): a string replaces searchText; an object may also refresh index declarations.

Returns

string

success on a completed write.

string

Human-readable result.

Example

import { Data } from 'lua-cli';

await Data.update('tickets', 'entry_abc123', { status: 'closed', closedAt: Date.now() });

Errors — Failed to update custom data entry when no entry has that id or the platform rejects the write.

search()

Returns the entries whose searchText is semantically closest to a query.

Data.search(collectionName: string, searchText: string, limit?: number, scoreThreshold?: number): Promise<DataEntryInstance[]>

string

required

Collection to search.

string

required

Natural-language query.

number

default:10

Maximum number of results. The maximum is 20.

number

default:0.6

Minimum similarity from 0 to 1. Results with a lower score are dropped.

Returns — a flat array of DataEntryInstance, each with a score from 0 to 1, best match first. Not the { data, pagination } envelope that get() returns. Example

import { Data } from 'lua-cli';

const matches = await Data.search('tickets', 'cannot sign in', 5, 0.7);
for (const match of matches) {
  console.log(match.subject, match.score);
}

Errors — none beyond network errors.

delete()

Deletes one entry.

Data.delete(collectionName: string, entryId: string): Promise<DeleteCustomDataResponse>

string

required

Collection that holds the entry.

string

required

The entry’s id.

Returns

string

success on a completed delete.

string

Human-readable result.

Example

import { Data } from 'lua-cli';

await Data.delete('tickets', 'entry_abc123');

Errors — Failed to delete custom data entry when no entry has that id.

DataEntryInstance

The object create(), getEntry(), and search() return. Fields of data are readable and writable directly (entry.subject) and through entry.data; direct assignments stay local until save().

string

Entry id.

string

The entry’s collection.

Record<string, any>

The stored object.

number

Similarity from 0 to 1. Set on search() results only.

update()

Merges fields into the entry on the server and locally.

entry.update(data: Record<string, any>, searchText?: string): Promise<Record<string, any>>

Returns — the merged data. Errors — Failed to update custom data entry, with the platform’s error as cause.

patch()

Sets and removes top-level fields, and optionally replaces or clears searchText, in one request.

entry.patch(mutation: { set?: Record<string, any>; unset?: string[]; searchText?: string | null }): Promise<Record<string, any>>

Record<string, any>

Fields to set. A null value is stored as null.

string[]

Top-level fields to remove.

string | null

A replacement searchText, or null to clear it.

Returns — the data after the mutation. Errors — Failed to patch custom data entry, with the platform’s error as cause.

unset()

Removes top-level fields; shorthand for patch({ unset: fields }).

entry.unset(...fields: string[]): Promise<Record<string, any>>

delete()

Deletes the entry.

entry.delete(): Promise<boolean>

Returns — true. Errors — Failed to delete custom data entry, with the platform’s error as cause.

save()

Writes the whole local data to the server, optionally with a replacement searchText.

entry.save(searchText?: string): Promise<boolean>

Returns — true. Example

import { Data } from 'lua-cli';

const ticket = await Data.getEntry('tickets', 'entry_abc123');
ticket.status = 'closed';
ticket.closedAt = Date.now();
await ticket.save();

Errors — Failed to save data entry, with the platform’s error as cause.

toJSON()

Returns { ...data, score, id, collectionName }, which is what JSON.stringify(entry) and console.log(entry) print.

shared()

Opens an organization’s shared collection: the same methods as Data, on data several agents of the organization read and some of them write. Available in lua-cli 3.50.0 and later.

Data.shared(name: string): SharedDataAPI

string

required

The shared collection’s name, as an org admin created it: 1 to 128 of A-Z a-z 0-9 _ . -. Any other value throws at once with code === 'shared_data_invalid_name'.

Returns — a SharedDataAPI with collections, create, get, getEntry, update, patch, increment, search and delete: the signatures, return shapes, filters, indexes and limits of the matching Data methods. A shared collection can hold several collections, named by the first argument as with Data. An entry instance it returns (update(), patch(), save(), delete()) writes back to the shared collection. Access — set by an org admin per collection, never by agent code (Share a collection between agents):

List	May call
`readers`	`collections`, `get`, `getEntry`, `search`
`writers`	Every method

Every write is recorded in the organization’s audit log with the agent, the collection and the entry id, never the value. The embedding work for searchText and search() is billed to the calling agent. Example

import { Data } from 'lua-cli';

const catalog = Data.shared('product_catalog');

// A writer:
const product = await catalog.create('products', { sku: 'RX-1', name: 'Router X1', price: 89 }, 'Router X1 dual-band Wi-Fi router');

// A reader:
const matches = await catalog.search('products', 'wifi router', 5, 0.7);
const inStock = await catalog.get('products', { price: { $lte: 100 } }, 1, 20);

Errors — a refused call rejects with an error whose code is:

`code`	Status	When
`shared_data_forbidden`	403	The agent is not on the list this call needs, or the name does not exist or belongs to another organization. These are never told apart
`shared_data_test_session_write_refused`	409	A write in a test session. Reads are allowed
`shared_data_unavailable_offline`		Any call under `lua test` or another local run, which cannot check the organization’s lists. Thrown as `SharedDataError`
`shared_data_invalid_name`		`name` is not a valid shared collection name

Limits

Limit	Value
`get()` entries per page	100
`search()` results	20
`scoreThreshold`	0 to 1
Fields per index	2
Index declarations per call	3
Indexes per agent	5
Queued, unbuilt declarations per agent	10
Index kept after last declaration or filtered read	14 days
Index field path	Dotted, up to 5 segments of letters, digits, `_`, `-`; no `$`, no numeric segment
Filter size, depth, and operands	See Lua Query limits

The same limits apply to a shared collection opened with shared(); its indexes count against the shared collection, not the calling agent.

Types

DataEntryInstance, LuaQuery, the SharedDataAPI type that shared() returns, and the SharedDataError class are exported. The result shapes (CustomDataEntry, GetCustomDataResponse, CreateCustomDataOptions, CustomDataCollectionsResponse, UpdateCustomDataResponse, DeleteCustomDataResponse) are not; name them from the method that returns them.

import { Data } from 'lua-cli';
import type { DataEntryInstance, LuaQuery } from 'lua-cli';

type GetPage = Awaited<ReturnType<typeof Data.get>>;
type CreateOptions = Exclude<Parameters<typeof Data.create>[2], string | undefined>;

export async function openTickets(filter: LuaQuery): Promise<GetPage> {
  return Data.get('tickets', filter);
}

export function firstHit(results: DataEntryInstance[]): DataEntryInstance | undefined {
  return results[0];
}

export const indexed: CreateOptions = { index: ['accountId', ['country', 'accountId']] };

SDK

CLI

REST API

Quick example

Methods

collections()

create()

get()

getEntry()

update()

search()

delete()

DataEntryInstance

update()

patch()

unset()

delete()

save()

toJSON()

shared()

Limits

Types

See also

​Quick example

​Methods

​collections()

​create()

​get()

​getEntry()

​update()

​search()

​delete()

​DataEntryInstance

​update()

​patch()

​unset()

​delete()

​save()

​toJSON()

​shared()

​Limits

​Types

​See also

Quick example

Methods

collections()

create()

get()

getEntry()

update()

search()

delete()

DataEntryInstance

update()

patch()

unset()

delete()

save()

toJSON()

shared()

Limits

Types

See also