dm-limits-and-best-practices

CDF Data Modeling: Limits, Concurrency & Best Practices

This is a reference skill. When writing or reviewing code that calls CDF Data Modeling APIs, apply the patterns below.

This skill owns runtime reliability concerns: limits, concurrency, retries, throughput, and batching behavior. For traversal payload correctness and graph-specific failure signatures, see dm-graph-traversal.

---

DMS Limits Reference

For the latest concurrency limits, resource limits, and property value limits, see the official documentation: https://docs.cognite.com/cdf/dm/dm_reference/dm_limits_and_restrictions

Key things to be aware of:

• Instance apply, delete, and query operations each have their own concurrent request limits
• Exceeding these limits returns 429 Too Many Requests
• Transformations consume a large portion of the concurrency budget, leaving less for other clients
• instances.list has a max page size (use pagination for complete results)
• instances.query table expressions each have their own item limit
• instances.upsert accepts up to 1000 items per call
• in filters accept at most 1000 values per expression; larger sets must be split into batches

---

Search vs Filter: When to Use Which

instances.search — Free-text search on text properties

Use instances.search when you need fuzzy/text matching on string fields (names, descriptions, etc.). It supports an operator parameter:

• AND (default) — Narrow search. All terms must match. Use when the user provides a specific query.
• OR — Broad "shotgun" search. Any term can match. Use for exploratory/typeahead search where you want maximum recall.

// Narrow search: find a specific cell by name (AND — all terms must match)
const exactResults = await client.instances.search({
  view: { type: 'view', ...PROCESS_CELL_VIEW },
  query: 'reactor tank A',
  properties: ['name'],
  operator: 'AND',
  limit: 10,
});

// Broad search: typeahead/autocomplete (OR — any term can match)
const broadResults = await client.instances.search({
  view: { type: 'view', ...BATCH_VIEW },
  query: 'BUDE completed',
  properties: ['name', 'description', 'batchStatus'],
  operator: 'OR',
  limit: 10,
});