industrial-model 0.4.0 → 0.5.0

package/README.md

@@ -6,6 +6,7 @@ TypeScript SDK for querying [Cognite Flexible Data Models (FDM)](https://docs.co
 
 - **Type-safe queries** — define your data model types once, get compile-time validation on filters, selects, and sorts
 - **Relation traversal** — query nested relations (edges/nodes) up to 3 levels deep with automatic pagination
+- **Text search filters** — use Cognite `instances.search` from query and aggregate filters on text fields
 - **Dual CJS/ESM** — works in Node.js and bundlers out of the box
 - **Cursor-based pagination** — built-in support for iterating large result sets
 
@@ -60,7 +61,7 @@ const { items } = await model.query<{ name: string; description: string }>()({
 | Setup & types | [Shared type definitions](#shared-type-definitions) |
 | Basic queries | [Query assets](#query-assets), [Single asset](#query-a-single-asset-by-externalid) |
 | Relations | [Parent/root](#query-assets-with-parent-and-root-relations), [Path](#query-assets-with-their-full-path), [Children](#query-child-assets-reverse-relation), [Edges](#traverse-edge-relations-360-images-on-3d-objects) |
-| Filters | [AND/OR/NOT](#combine-filters-with-and--or--not), [Nested](#filter-on-related-nodes), [Tags](#filter-assets-by-tags), [Batch IDs](#filter-by-multiple-external-ids) |
+| Filters | [AND/OR/NOT](#combine-filters-with-and--or--not), [Text search](#search-text-fields), [Nested](#filter-on-related-nodes), [Tags](#filter-assets-by-tags), [Batch IDs](#filter-by-multiple-external-ids) |
 | Select & sort | [Select all scalars](#select-all-scalar-fields), [Multi-field sort](#sort-by-multiple-fields) |
 | Pagination | [Manual cursor loop](#paginate-through-all-assets), [Fetch all pages](#fetch-all-pages-automatically) |
 | Aggregation | [Count by group](#count-assets-by-source-id), [Distinct values](#list-distinct-source-ids), [Numeric aggregates](#average-volume-by-type), [Global count](#count-all-matching-assets) |
@@ -469,6 +470,52 @@ const fullyTagged = await model.query<CogniteAsset>()({
 
 ---
 
+### Search text fields
+
+Use `search` on text properties and string-list text properties when you want Cognite full-text matching instead of exact or prefix filters. The optional `operator` is passed to Cognite search and defaults to `"OR"`; use `"AND"` when every term should match.
+
+```ts
+const { items } = await model.query<CogniteAsset>()({
+  viewExternalId: "CogniteAsset",
+  select: { name: true, description: true, tags: true },
+  filters: {
+    name: { search: { query: "root pump", operator: "AND" } },
+    tags: { search: { query: "critical" } },
+  },
+  limit: 100,
+});
+```
+
+Search filters can be combined with normal field operators. The SDK first calls Cognite `instances.search`, then adds the returned node references to the regular query filter.
+
+```ts
+const pumps = await model.query<CogniteAsset>()({
+  viewExternalId: "CogniteAsset",
+  select: { name: true, sourceId: true },
+  filters: {
+    name: {
+      prefix: "Pump",
+      search: { query: "motor" },
+    },
+    sourceId: { exists: true },
+  },
+});
+```
+
+The same filter syntax is also supported by `aggregate`:
+
+```ts
+const { items } = await model.aggregate<CogniteAsset>()({
+  viewExternalId: "CogniteAsset",
+  aggregate: { count: {} },
+  filters: {
+    name: { search: { query: "compressor seal" } },
+  },
+});
+```
+
+---
+
 ### Filter on related nodes
 
 Filter the root view based on properties of a direct or nested relation. This uses Cognite nested filters under the hood.
@@ -912,15 +959,18 @@ See [Count assets by source ID](#count-assets-by-source-id), [List distinct sour
 
 | Type | Operators |
 |------|-----------|
-| `string` | `eq`, `in`, `prefix`, `exists` |
+| `string` | `eq`, `in`, `prefix`, `search`, `exists` |
 | `number` | `eq`, `in`, `gt`, `gte`, `lt`, `lte`, `exists` |
 | `boolean` | `eq`, `exists` |
 | timestamp / `Date` | `eq`, `in`, `gt`, `gte`, `lt`, `lte`, `exists` — use ISO strings or `Date` values (coerced to ISO) |
 | `NodeId` | `eq`, `in`, `exists` |
+| `string[]` | `containsAny`, `containsAll`, `search`, `exists` |
 | `T[]` | `containsAny`, `containsAll`, `exists` |
 
 Logical combinators `AND`, `OR`, and `NOT` are supported at any nesting level, including inside nested relation filters (e.g. `parent: { OR: [...] }`).
 
+`search` is available for Cognite text properties and string-list text properties. It is not accepted on node metadata fields such as `externalId` or `space`. Each `search` filter uses `instances.search` with `limit: 1000`, maps the matched nodes to `instanceReferences`, and applies those references to the query or aggregate request.
+
 ### Relation traversal
 
 - **Direct relations** — `parent`, `asset`, `unit` (outwards from the current node). List relations such as `path` return arrays when expanded.

package/dist/index.cjs

@@ -28,6 +28,13 @@ var CogniteSdkAdapter = class {
       nextCursor: response.nextCursor
     };
   }
+  async searchInstances(request) {
+    const search = this.client.instances.search;
+    const response = await search(request);
+    return {
+      items: response.items
+    };
+  }
   async aggregateInstances(request) {
     const response = await this.client.instances.aggregate(
       request
@@ -186,6 +193,7 @@ var leafOps = /* @__PURE__ */ new Set([
   "lte",
   "exists",
   "prefix",
+  "search",
   "containsAny",
   "containsAll"
 ]);
@@ -238,19 +246,33 @@ function leafFilterSchema(property) {
   const value = baseValueSchema(property);
   const isList = typeof property !== "string" && property.type.list === true;
   if (isList) {
-    return zod.z.object({
+    const shape = {
       containsAny: zod.z.array(value).optional(),
       containsAll: zod.z.array(value).optional(),
       exists: zod.z.boolean().optional()
-    }).strict();
+    };
+    if (property.type.type === "text") {
+      shape.search = zod.z.object({
+        query: zod.z.string(),
+        operator: zod.z.enum(["OR", "AND"]).optional()
+      }).strict().optional();
+    }
+    return zod.z.object(shape).strict();
   }
   if (property === "node-string" || typeof property !== "string" && property.type.type === "text") {
-    return zod.z.object({
+    const shape = {
       eq: zod.z.string().optional(),
       in: zod.z.array(zod.z.string()).optional(),
       prefix: zod.z.string().optional(),
       exists: zod.z.boolean().optional()
-    }).strict();
+    };
+    if (property !== "node-string") {
+      shape.search = zod.z.object({
+        query: zod.z.string(),
+        operator: zod.z.enum(["OR", "AND"]).optional()
+      }).strict().optional();
+    }
+    return zod.z.object(shape).strict();
   }
   if (typeof property !== "string" && property.type.type === "enum") {
     return zod.z.object({
@@ -610,11 +632,13 @@ function isLeafFilter2(value) {
   return Object.keys(value).some((k) => LEAF_OPS.has(k));
 }
 var FilterMapper = class {
-  constructor(viewMapper) {
+  constructor(viewMapper, cognite) {
     this.viewMapper = viewMapper;
+    this.cognite = cognite;
   }
   async map(input, rootView) {
     const result = [];
+    const searchQueries = {};
     for (const [key, value] of Object.entries(input)) {
       if (value == null) continue;
       if (key === "AND") {
@@ -635,17 +659,44 @@ var FilterMapper = class {
       } else {
         const filterValue = value;
         const property = getPropertyRef(key, rootView);
-        if (isLeafFilter2(filterValue)) {
+        const hasLeafFilter = isLeafFilter2(filterValue);
+        if (hasLeafFilter) {
           result.push(...this.leafToFilterDefs(property, filterValue));
-        } else {
+        }
+        if ("search" in filterValue && filterValue.search != null) {
+          searchQueries[key] = filterValue.search;
+        } else if (!hasLeafFilter) {
           const targetView = await this.getNestedTargetView(key, rootView);
           const innerFilter = await this.whereInputToSingle(filterValue, targetView);
           result.push({ nested: { scope: property, filter: innerFilter } });
         }
       }
     }
+    if (Object.keys(searchQueries).length > 0) {
+      const searchFilters = await Promise.all(
+        Object.entries(searchQueries).map(
+          ([key, filterValue]) => this.searchToFilterDef(key, filterValue, rootView)
+        )
+      );
+      result.push(...searchFilters);
+    }
     return result;
   }
+  async searchToFilterDef(propertyName, search, rootView) {
+    const response = await this.cognite.searchInstances({
+      view: toViewReference(rootView),
+      query: search.query,
+      instanceType: "node",
+      properties: [propertyName],
+      operator: search.operator ?? "OR",
+      limit: 1e3
+    });
+    const instanceRefs = response.items.map((item) => ({
+      space: item.space,
+      externalId: item.externalId
+    }));
+    return { instanceReferences: instanceRefs };
+  }
   async whereInputToSingle(input, rootView) {
     const filters = await this.map(input, rootView);
     const [firstFilter, ...restFilters] = filters;
@@ -724,9 +775,9 @@ var FilterMapper = class {
 
 // src/mappers/aggregate-mapper.ts
 var AggregateMapper = class {
-  constructor(viewMapper) {
+  constructor(viewMapper, cognite) {
     this.viewMapper = viewMapper;
-    this.filterMapper = new FilterMapper(viewMapper);
+    this.filterMapper = new FilterMapper(viewMapper, cognite);
     this.validator = new AggregateValidator(viewMapper);
   }
   async map(options) {
@@ -821,9 +872,9 @@ var SortMapper = class {
 
 // src/mappers/query-mapper.ts
 var QueryMapper = class {
-  constructor(viewMapper) {
+  constructor(viewMapper, cognite) {
     this.viewMapper = viewMapper;
-    this.filterMapper = new FilterMapper(viewMapper);
+    this.filterMapper = new FilterMapper(viewMapper, cognite);
     this.sortMapper = new SortMapper();
     this.validator = new QueryValidator(viewMapper);
   }
@@ -1369,8 +1420,8 @@ var IndustrialModelClient = class {
     const cognite = createCogniteAdapter(client);
     this.cognite = cognite;
     const viewMapper = new ViewMapper(cognite, dataModelId);
-    this.queryMapper = new QueryMapper(viewMapper);
-    this.aggregateMapper = new AggregateMapper(viewMapper);
+    this.queryMapper = new QueryMapper(viewMapper, cognite);
+    this.aggregateMapper = new AggregateMapper(viewMapper, cognite);
     this.aggregateResultMapper = new AggregateResultMapper();
     this.resultMapper = new QueryResultMapper(viewMapper);
     this.resultValidator = new QueryResultValidator(viewMapper);