ExuluReadApi - IMP Docs

ExuluReadApi provides low-level, RBAC-enforced read functions for knowledge contexts. Where ExuluContext.search() covers relevance-ranked retrieval, ExuluReadApi covers targeted reads by item ID or external ID, embed-query utilities, and table-name resolution — all while applying the same access-control rules as the GraphQL layer. Use ExuluReadApi when you need to read specific known items without going through vector search, or when you need the underlying table names to build custom queries.

API surface

ExuluReadApi.authorizedRead

ExuluReadApi.authorizedRead(
  context: { id: string; fields?: unknown[]; entities?: unknown },
  user: User,
  role: string,
  opts?: {
    itemIds?: string[];
    externalIds?: string[];
    chunkIndexRange?: { from?: number; to?: number };
  },
): Promise<VectorSearchChunkResult[]>

Reads chunks from a context, joining them to their parent items and applying RBAC via applyAccessControl. At least itemIds or externalIds must be supplied — unconstrained full-table reads are rejected.

context

object

required

The context to read from. Must have an id matching a registered ExuluContext.

user

User

required

Authenticated user. Used for RBAC filtering on the items table.

role

string

required

Role ID. Merged into the user object so access-control’s role branch works correctly.

opts.itemIds

string[]

Filter to chunks whose parent item ID is in this list.

opts.externalIds

string[]

Filter to chunks whose parent item external_id is in this list.

opts.chunkIndexRange

{ from?: number; to?: number }

Restrict to a contiguous range of chunk_index values within the matched items.

return

Promise<VectorSearchChunkResult[]>

Chunk rows with joined item metadata, ordered by (source, chunk_index).

ExuluReadApi.embedQuery

ExuluReadApi.embedQuery(
  context: { id: string; name?: string; embedder: { model: string } },
  text: string,
  opts?: {
    user?: User;
    role?: string;
    inputType?: "document" | "query";
  },
): Promise<number[]>

Embeds a text string using the context’s configured embedder model. Returns the embedding vector as a number array.

ExuluReadApi.entitiesAvailable

ExuluReadApi.entitiesAvailable(
  context: { id: string; entities?: unknown },
): Promise<boolean>

Returns true when the context declares an entities config and the corresponding _chunk_entities table physically exists. Use this to guard entity tool registration at runtime.

Table-name helpers

ExuluReadApi.getTableName(contextId: string): string
ExuluReadApi.getChunksTableName(contextId: string): string
ExuluReadApi.getEntitiesTableName(contextId: string): string
ExuluReadApi.getChunkEntitiesTableName(contextId: string): string

Return the Postgres table names used by the given context. Useful when building custom queries directly against the database.

Example

import { ExuluReadApi, postgresClient } from "@exulu/backend";

// Read all chunks for two known items, respecting RBAC
const chunks = await ExuluReadApi.authorizedRead(
  productDocsContext,
  req.user,
  req.user.role?.id ?? "viewer",
  { itemIds: ["item-abc", "item-def"] },
);

// Stream chunk content to the calling agent
for (const chunk of chunks) {
  console.log(chunk.item_name, chunk.chunk_index, chunk.chunk_content);
}

Resolve table names for a custom Knex query:

const { db } = await postgresClient();
const chunksTable = ExuluReadApi.getChunksTableName("product_docs");

const recent = await db(chunksTable)
  .where("chunk_index", 0)
  .orderBy("createdAt", "desc")
  .limit(10);

Notes

authorizedRead always applies RBAC via applyAccessControl on the items alias — this gate cannot be bypassed through opts.
Results are ordered by (chunks.source, chunks.chunk_index) — stable page order for items with multiple chunks.
embedQuery routes through the same resolveEmbedder path as the ingestion pipeline, so LiteLLM cost attribution applies.

ExuluContext — introduction: ExuluContext.search() for relevance-ranked retrieval.
VectorSearchChunkResult: shape of the returned chunk rows.

​API surface

​ExuluReadApi.authorizedRead

​ExuluReadApi.embedQuery

​ExuluReadApi.entitiesAvailable

​Table-name helpers

​Example

​Notes

​Related

API surface

ExuluReadApi.authorizedRead

ExuluReadApi.embedQuery

ExuluReadApi.entitiesAvailable

Table-name helpers

Example

Notes

Related