@pulseindex/sdk 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 3.2.0
+
+### Delete many entities in one call
+
+`delete()` takes a single id, so clearing a catalogue meant one round trip per
+row. There was no other way to do it through the API at all.
+
+```ts
+for (const page of pages(idsToRemove, 10_000)) {
+  const { deletedCount } = await client.batchDelete(page);
+}
+```
+
+Up to 10,000 ids per call. A larger page is refused by name rather than
+truncated, so a page that is too big fails loudly instead of deleting part of
+itself and reporting success.
+
+Ids that are unknown or already deleted are skipped rather than refused, so
+retrying a page that half-applied is safe. `deletedCount` is the number of rows
+that actually changed, which is lower than the number of ids you sent whenever
+some were already gone.
+
+## 3.1.0
+
+### A radius no longer merges with your own OR
+
+`withinRadius` turns a circle into one SHOULD filter per covering geohash cell.
+Every SHOULD went into the same disjunction, so a radius sat in the same OR as
+anything else you had asked for:
+
+```ts
+PulseIndex.query().should(['color:red', 'color:blue']).withinRadius(lat, lon, 5)
+```
+
+asked for "within 5 km **or** red **or** blue". It returned a plausible page of
+results and said nothing about it. The cells now form a disjunction of their
+own, and each further radius gets another, so that query means what it reads
+like. Nothing changes for a query that used one or the other but not both.
+
+### Groups: (red or blue) and (small or medium)
+
+`should()` takes a group number. Members of a group are OR'd together and the
+groups are AND'd with each other:
+
+```ts
+PulseIndex.query()
+  .should(['color:red', 'color:blue'], 1)
+  .should(['size:s', 'size:m'], 2);
+```
+
+Left unset it is 0, which is one disjunction — exactly what every existing
+query already does.
+
+### Ordering
+
+`sortAsc(field)`, `sortDesc(field)` and `sortBy(field, descending)`, plus
+`sortBy` on the plain options form:
+
+```ts
+await client.search(PulseIndex.query().must('status:active').sortAsc('price'));
+```
+
+Rows carrying no value for the field sort last in both directions; they still
+count towards `totalMatches`, they simply have nothing to be ordered by.
+
+An ordered search cannot stop as soon as the page is full — the cheapest
+remaining row may be anywhere in the tenant — so it costs more than the same
+filter unordered. `offset + limit` is capped at 100,000 and a request past it
+is refused with the ceiling named.
+
 ## 3.0.0
 
 ### Breaking: a query returns a page instead of everything

package/README.md

@@ -140,6 +140,10 @@ await client.batchIndex([
 ]);
 
 await client.delete('1001');
+
+// Clearing many rows: send ids in pages of up to 10,000. A larger page is
+// refused by name rather than truncated.
+await client.batchDelete([1002, 1003, 1004]);
 ```
 
 Low-level PHP-compatible helper:
@@ -293,6 +297,7 @@ than failing your own requests immediately; if it persists, contact support.
 | `client.index(id, attributes)` | `{ success }` | Upsert one entity |
 | `client.batchIndex(entities)` | `{ indexedCount }` | Batch upsert |
 | `client.delete(id)` | `{ success }` | Soft-delete an entity |
+| `client.batchDelete(ids)` | `{ deletedCount }` | Soft-delete up to 10,000 entities in one call |
 | `client.health()` | `boolean` | Whether the service is ready to answer queries |
 | `client.servingStatus()` | `number` | Readiness as a status code, when you need more than a boolean |
 | `client.close()` | `void` | Shut down the channel pool |

package/dist/index.d.mts

@@ -11,6 +11,22 @@ type EntityId = string | number | bigint;
 interface FilterPredicate {
     op: FilterOperationCode;
     attribute: string;
+    /**
+     * Which disjunction a SHOULD predicate belongs to. Ignored for MUST and
+     * MUST_NOT.
+     *
+     * Members of a group are OR'd together and the groups are AND'd with each
+     * other, so "(red or blue) and (small or medium)" is two groups. Predicates
+     * that leave this unset share group 0.
+     */
+    group?: number;
+}
+/** Orders a page by a numeric field. */
+interface SortSpec {
+    /** Numeric field name, the same one a range would name. */
+    field: string;
+    /** Largest first when true; smallest first otherwise. */
+    descending: boolean;
 }
 interface RangePredicate {
     field: string;
@@ -24,6 +40,8 @@ interface SearchQueryRequest {
     limit: number;
     offset: number;
     tenantId: string;
+    /** Absent returns matches in entity-id order. */
+    sort?: SortSpec;
 }
 interface SearchResponse {
     matchedEntityIds: string[];
@@ -46,6 +64,13 @@ interface BatchIndexResponse {
 interface DeleteResponse {
     success: boolean;
 }
+interface BatchDeleteResponse {
+    /**
+     * How many rows actually changed. Lower than the number of ids sent when
+     * some were unknown or already deleted, which is not an error.
+     */
+    deletedCount: number;
+}
 interface RadiusOptions {
     lat: number;
     lng?: number;
@@ -68,6 +93,16 @@ interface SearchRequestOptions {
     offset?: number;
     withinRadius?: RadiusOptions;
     geoHash?: string;
+    /**
+     * Order the page by a numeric field. `descending` defaults to false.
+     *
+     * Rows carrying no value for the field sort last in both directions. They
+     * still count towards `totalMatches`; they have nothing to be ordered by.
+     */
+    sortBy?: {
+        field: string;
+        descending?: boolean;
+    };
 }
 interface EntityAttributes {
     categories?: unknown;
@@ -154,7 +189,17 @@ declare class QueryBuilder {
     tenant(tenantId: string): QueryBuilder;
     location(locationPrefix: string | number | bigint): QueryBuilder;
     must(attribute: string | string[]): QueryBuilder;
-    should(attribute: string | string[]): QueryBuilder;
+    /**
+     * At least one of these has to match.
+     *
+     * Pass a `group` to keep a disjunction separate from another one. Members of
+     * a group are OR'd together and the groups are AND'd with each other, so
+     * `.should(['color:red', 'color:blue'], 1).should(['size:s', 'size:m'], 2)`
+     * asks for a red or blue shirt in small or medium. Without the group numbers
+     * all four collapse into a single OR, which answers a different question and
+     * says nothing about it.
+     */
+    should(attribute: string | string[], group?: number): QueryBuilder;
     mustNot(attribute: string | string[]): QueryBuilder;
     whereGeoHash(geohash: string): QueryBuilder;
     inGeoHash(geohash: string): QueryBuilder;
@@ -167,6 +212,22 @@ declare class QueryBuilder {
      */
     limit(limit: number): QueryBuilder;
     offset(offset: number): QueryBuilder;
+    /**
+     * Order the page by a numeric field, smallest first.
+     *
+     * An ordered search cannot stop as soon as the page is full — the cheapest
+     * remaining row may be anywhere in the tenant — so it costs more than the
+     * same filter unordered. `offset + limit` is capped at 100,000.
+     */
+    sortAsc(field: string): QueryBuilder;
+    /** Order the page by a numeric field, largest first. */
+    sortDesc(field: string): QueryBuilder;
+    /**
+     * Order the page by a numeric field. Rows carrying no value for it sort last
+     * in both directions; they still count towards `totalMatches`, they simply
+     * have nothing to be ordered by.
+     */
+    sortBy(field: string, descending?: boolean): QueryBuilder;
     toRequest(defaultTenantId?: string): SearchQueryRequest;
     toArray(defaultTenantId?: string): SearchQueryRequest;
     execute(): Promise<SearchResponse>;
@@ -179,6 +240,7 @@ interface SearchEngineServiceClient extends grpc.Client {
     indexEntity(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     batchIndexEntities(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     deleteEntity(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
+    batchDeleteEntities(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     search(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
 }
 /** `grpc.health.v1.Health` — the readiness check that needs no scope. */
@@ -241,6 +303,26 @@ declare class PulseIndexClient implements QueryExecutor {
     batchIndex(entities: Array<EntityInput | BatchEntityInput>): Promise<BatchIndexResponse>;
     delete(entityId: EntityId, tenantId?: string): Promise<DeleteResponse>;
     deleteEntity(entityId: EntityId, tenantId?: string): Promise<boolean>;
+    /**
+     * Delete many entities in one call.
+     *
+     * `delete` takes a single id, so clearing a catalogue that way is one round
+     * trip per row. Send ids in pages of up to 10,000; the engine refuses a
+     * larger batch by name rather than truncating it, so a page that is too big
+     * fails loudly instead of deleting part of itself.
+     *
+     * Ids that are unknown or already deleted are skipped, so retrying a page
+     * that half-applied is safe. `deletedCount` is the number of rows that
+     * actually changed, which is lower than `entityIds.length` whenever some of
+     * them were already gone.
+     *
+     * ```ts
+     * for (const page of pages(allIds, 10_000)) {
+     *   await client.batchDelete(page);
+     * }
+     * ```
+     */
+    batchDelete(entityIds: readonly EntityId[], tenantId?: string): Promise<BatchDeleteResponse>;
     /**
      * True only when the engine can serve reads.
      *
@@ -334,4 +416,4 @@ declare class PulseIndexQueryError extends PulseIndexError {
     constructor(message: string, options?: ConstructorParameters<typeof PulseIndexError>[1]);
 }
 
-export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };
+export { type BatchDeleteResponse, type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, type SortSpec, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };

package/dist/index.d.ts

@@ -11,6 +11,22 @@ type EntityId = string | number | bigint;
 interface FilterPredicate {
     op: FilterOperationCode;
     attribute: string;
+    /**
+     * Which disjunction a SHOULD predicate belongs to. Ignored for MUST and
+     * MUST_NOT.
+     *
+     * Members of a group are OR'd together and the groups are AND'd with each
+     * other, so "(red or blue) and (small or medium)" is two groups. Predicates
+     * that leave this unset share group 0.
+     */
+    group?: number;
+}
+/** Orders a page by a numeric field. */
+interface SortSpec {
+    /** Numeric field name, the same one a range would name. */
+    field: string;
+    /** Largest first when true; smallest first otherwise. */
+    descending: boolean;
 }
 interface RangePredicate {
     field: string;
@@ -24,6 +40,8 @@ interface SearchQueryRequest {
     limit: number;
     offset: number;
     tenantId: string;
+    /** Absent returns matches in entity-id order. */
+    sort?: SortSpec;
 }
 interface SearchResponse {
     matchedEntityIds: string[];
@@ -46,6 +64,13 @@ interface BatchIndexResponse {
 interface DeleteResponse {
     success: boolean;
 }
+interface BatchDeleteResponse {
+    /**
+     * How many rows actually changed. Lower than the number of ids sent when
+     * some were unknown or already deleted, which is not an error.
+     */
+    deletedCount: number;
+}
 interface RadiusOptions {
     lat: number;
     lng?: number;
@@ -68,6 +93,16 @@ interface SearchRequestOptions {
     offset?: number;
     withinRadius?: RadiusOptions;
     geoHash?: string;
+    /**
+     * Order the page by a numeric field. `descending` defaults to false.
+     *
+     * Rows carrying no value for the field sort last in both directions. They
+     * still count towards `totalMatches`; they have nothing to be ordered by.
+     */
+    sortBy?: {
+        field: string;
+        descending?: boolean;
+    };
 }
 interface EntityAttributes {
     categories?: unknown;
@@ -154,7 +189,17 @@ declare class QueryBuilder {
     tenant(tenantId: string): QueryBuilder;
     location(locationPrefix: string | number | bigint): QueryBuilder;
     must(attribute: string | string[]): QueryBuilder;
-    should(attribute: string | string[]): QueryBuilder;
+    /**
+     * At least one of these has to match.
+     *
+     * Pass a `group` to keep a disjunction separate from another one. Members of
+     * a group are OR'd together and the groups are AND'd with each other, so
+     * `.should(['color:red', 'color:blue'], 1).should(['size:s', 'size:m'], 2)`
+     * asks for a red or blue shirt in small or medium. Without the group numbers
+     * all four collapse into a single OR, which answers a different question and
+     * says nothing about it.
+     */
+    should(attribute: string | string[], group?: number): QueryBuilder;
     mustNot(attribute: string | string[]): QueryBuilder;
     whereGeoHash(geohash: string): QueryBuilder;
     inGeoHash(geohash: string): QueryBuilder;
@@ -167,6 +212,22 @@ declare class QueryBuilder {
      */
     limit(limit: number): QueryBuilder;
     offset(offset: number): QueryBuilder;
+    /**
+     * Order the page by a numeric field, smallest first.
+     *
+     * An ordered search cannot stop as soon as the page is full — the cheapest
+     * remaining row may be anywhere in the tenant — so it costs more than the
+     * same filter unordered. `offset + limit` is capped at 100,000.
+     */
+    sortAsc(field: string): QueryBuilder;
+    /** Order the page by a numeric field, largest first. */
+    sortDesc(field: string): QueryBuilder;
+    /**
+     * Order the page by a numeric field. Rows carrying no value for it sort last
+     * in both directions; they still count towards `totalMatches`, they simply
+     * have nothing to be ordered by.
+     */
+    sortBy(field: string, descending?: boolean): QueryBuilder;
     toRequest(defaultTenantId?: string): SearchQueryRequest;
     toArray(defaultTenantId?: string): SearchQueryRequest;
     execute(): Promise<SearchResponse>;
@@ -179,6 +240,7 @@ interface SearchEngineServiceClient extends grpc.Client {
     indexEntity(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     batchIndexEntities(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     deleteEntity(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
+    batchDeleteEntities(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
     search(request: unknown, metadata: grpc.Metadata, options: grpc.CallOptions, callback: grpc.requestCallback<unknown>): grpc.ClientUnaryCall;
 }
 /** `grpc.health.v1.Health` — the readiness check that needs no scope. */
@@ -241,6 +303,26 @@ declare class PulseIndexClient implements QueryExecutor {
     batchIndex(entities: Array<EntityInput | BatchEntityInput>): Promise<BatchIndexResponse>;
     delete(entityId: EntityId, tenantId?: string): Promise<DeleteResponse>;
     deleteEntity(entityId: EntityId, tenantId?: string): Promise<boolean>;
+    /**
+     * Delete many entities in one call.
+     *
+     * `delete` takes a single id, so clearing a catalogue that way is one round
+     * trip per row. Send ids in pages of up to 10,000; the engine refuses a
+     * larger batch by name rather than truncating it, so a page that is too big
+     * fails loudly instead of deleting part of itself.
+     *
+     * Ids that are unknown or already deleted are skipped, so retrying a page
+     * that half-applied is safe. `deletedCount` is the number of rows that
+     * actually changed, which is lower than `entityIds.length` whenever some of
+     * them were already gone.
+     *
+     * ```ts
+     * for (const page of pages(allIds, 10_000)) {
+     *   await client.batchDelete(page);
+     * }
+     * ```
+     */
+    batchDelete(entityIds: readonly EntityId[], tenantId?: string): Promise<BatchDeleteResponse>;
     /**
      * True only when the engine can serve reads.
      *
@@ -334,4 +416,4 @@ declare class PulseIndexQueryError extends PulseIndexError {
     constructor(message: string, options?: ConstructorParameters<typeof PulseIndexError>[1]);
 }
 
-export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };
+export { type BatchDeleteResponse, type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, type SortSpec, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };

package/dist/index.js

@@ -392,7 +392,9 @@ function emptyState() {
     limit: DEFAULT_LIMIT,
     offset: 0,
     filters: [],
-    ranges: []
+    ranges: [],
+    sort: null,
+    nextGroup: 1
   };
 }
 function asAttributeList(value) {
@@ -430,8 +432,18 @@ var QueryBuilder = class _QueryBuilder {
   must(attribute) {
     return this.addFilters(FilterOperation.MUST, attribute);
   }
-  should(attribute) {
-    return this.addFilters(FilterOperation.SHOULD, attribute);
+  /**
+   * At least one of these has to match.
+   *
+   * Pass a `group` to keep a disjunction separate from another one. Members of
+   * a group are OR'd together and the groups are AND'd with each other, so
+   * `.should(['color:red', 'color:blue'], 1).should(['size:s', 'size:m'], 2)`
+   * asks for a red or blue shirt in small or medium. Without the group numbers
+   * all four collapse into a single OR, which answers a different question and
+   * says nothing about it.
+   */
+  should(attribute, group = 0) {
+    return this.addFilters(FilterOperation.SHOULD, attribute, group);
   }
   mustNot(attribute) {
     return this.addFilters(FilterOperation.MUST_NOT, attribute);
@@ -463,10 +475,13 @@ var QueryBuilder = class _QueryBuilder {
     }
     const covering = GeoHash.getCoveringHashes(lat, longitude, radius, resolvedPrecision);
     return this.fork((state) => {
+      const group = state.nextGroup;
+      state.nextGroup += 1;
       for (const hash of covering) {
         state.filters.push({
           op: FilterOperation.SHOULD,
-          attribute: GeoHash.tag(hash)
+          attribute: GeoHash.tag(hash),
+          group
         });
       }
     });
@@ -503,8 +518,35 @@ var QueryBuilder = class _QueryBuilder {
       state.offset = Math.max(0, Math.floor(offset));
     });
   }
+  /**
+   * Order the page by a numeric field, smallest first.
+   *
+   * An ordered search cannot stop as soon as the page is full — the cheapest
+   * remaining row may be anywhere in the tenant — so it costs more than the
+   * same filter unordered. `offset + limit` is capped at 100,000.
+   */
+  sortAsc(field) {
+    return this.sortBy(field, false);
+  }
+  /** Order the page by a numeric field, largest first. */
+  sortDesc(field) {
+    return this.sortBy(field, true);
+  }
+  /**
+   * Order the page by a numeric field. Rows carrying no value for it sort last
+   * in both directions; they still count towards `totalMatches`, they simply
+   * have nothing to be ordered by.
+   */
+  sortBy(field, descending = false) {
+    if (!field.trim()) {
+      throw new PulseIndexQueryError("Sort field must not be empty.");
+    }
+    return this.fork((state) => {
+      state.sort = { field, descending };
+    });
+  }
   toRequest(defaultTenantId = "") {
-    return {
+    const request = {
       tenantId: this.state.tenantId || defaultTenantId,
       locationPrefix: this.state.locationPrefix,
       limit: this.state.limit,
@@ -512,6 +554,10 @@ var QueryBuilder = class _QueryBuilder {
       filters: this.state.filters.map((filter) => ({ ...filter })),
       ranges: this.state.ranges.map((range) => ({ ...range }))
     };
+    if (this.state.sort) {
+      request.sort = { ...this.state.sort };
+    }
+    return request;
   }
   toArray(defaultTenantId = "") {
     return this.toRequest(defaultTenantId);
@@ -558,13 +604,20 @@ var QueryBuilder = class _QueryBuilder {
     if (options.offset !== void 0) {
       query = query.offset(options.offset);
     }
+    if (options.sortBy !== void 0) {
+      query = query.sortBy(options.sortBy.field, options.sortBy.descending ?? false);
+    }
     return query;
   }
-  addFilters(op, attribute) {
+  addFilters(op, attribute, group = 0) {
     const attributes = asAttributeList(attribute);
+    const normalizedGroup = Math.max(0, Math.floor(group));
     return this.fork((state) => {
       for (const value of attributes) {
-        state.filters.push({ op, attribute: value });
+        state.filters.push({ op, attribute: value, group: normalizedGroup });
+      }
+      if (normalizedGroup >= state.nextGroup) {
+        state.nextGroup = normalizedGroup + 1;
       }
     });
   }
@@ -576,7 +629,9 @@ var QueryBuilder = class _QueryBuilder {
       limit: this.state.limit,
       offset: this.state.offset,
       filters: this.state.filters.map((filter) => ({ ...filter })),
-      ranges: this.state.ranges.map((range) => ({ ...range }))
+      ranges: this.state.ranges.map((range) => ({ ...range })),
+      sort: this.state.sort ? { ...this.state.sort } : null,
+      nextGroup: this.state.nextGroup
     };
     mutate(next.state);
     return next;
@@ -1091,6 +1146,40 @@ var PulseIndexClient = class _PulseIndexClient {
     const response = await this.delete(entityId, tenantId || this.connection.tenantId);
     return response.success;
   }
+  /**
+   * Delete many entities in one call.
+   *
+   * `delete` takes a single id, so clearing a catalogue that way is one round
+   * trip per row. Send ids in pages of up to 10,000; the engine refuses a
+   * larger batch by name rather than truncating it, so a page that is too big
+   * fails loudly instead of deleting part of itself.
+   *
+   * Ids that are unknown or already deleted are skipped, so retrying a page
+   * that half-applied is safe. `deletedCount` is the number of rows that
+   * actually changed, which is lower than `entityIds.length` whenever some of
+   * them were already gone.
+   *
+   * ```ts
+   * for (const page of pages(allIds, 10_000)) {
+   *   await client.batchDelete(page);
+   * }
+   * ```
+   */
+  async batchDelete(entityIds, tenantId) {
+    const ids = entityIds.map((id, i) => toUint64String(id, `entityIds[${i}]`));
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.batchDeleteEntities(
+        {
+          entityIds: ids,
+          tenantId: tenantId ?? this.connection.tenantId
+        },
+        metadata,
+        options,
+        callback
+      )
+    );
+    return { deletedCount: Number(raw.deletedCount ?? 0) };
+  }
   /**
    * True only when the engine can serve reads.
    *

package/dist/index.mjs

@@ -369,7 +369,9 @@ function emptyState() {
     limit: DEFAULT_LIMIT,
     offset: 0,
     filters: [],
-    ranges: []
+    ranges: [],
+    sort: null,
+    nextGroup: 1
   };
 }
 function asAttributeList(value) {
@@ -407,8 +409,18 @@ var QueryBuilder = class _QueryBuilder {
   must(attribute) {
     return this.addFilters(FilterOperation.MUST, attribute);
   }
-  should(attribute) {
-    return this.addFilters(FilterOperation.SHOULD, attribute);
+  /**
+   * At least one of these has to match.
+   *
+   * Pass a `group` to keep a disjunction separate from another one. Members of
+   * a group are OR'd together and the groups are AND'd with each other, so
+   * `.should(['color:red', 'color:blue'], 1).should(['size:s', 'size:m'], 2)`
+   * asks for a red or blue shirt in small or medium. Without the group numbers
+   * all four collapse into a single OR, which answers a different question and
+   * says nothing about it.
+   */
+  should(attribute, group = 0) {
+    return this.addFilters(FilterOperation.SHOULD, attribute, group);
   }
   mustNot(attribute) {
     return this.addFilters(FilterOperation.MUST_NOT, attribute);
@@ -440,10 +452,13 @@ var QueryBuilder = class _QueryBuilder {
     }
     const covering = GeoHash.getCoveringHashes(lat, longitude, radius, resolvedPrecision);
     return this.fork((state) => {
+      const group = state.nextGroup;
+      state.nextGroup += 1;
       for (const hash of covering) {
         state.filters.push({
           op: FilterOperation.SHOULD,
-          attribute: GeoHash.tag(hash)
+          attribute: GeoHash.tag(hash),
+          group
         });
       }
     });
@@ -480,8 +495,35 @@ var QueryBuilder = class _QueryBuilder {
       state.offset = Math.max(0, Math.floor(offset));
     });
   }
+  /**
+   * Order the page by a numeric field, smallest first.
+   *
+   * An ordered search cannot stop as soon as the page is full — the cheapest
+   * remaining row may be anywhere in the tenant — so it costs more than the
+   * same filter unordered. `offset + limit` is capped at 100,000.
+   */
+  sortAsc(field) {
+    return this.sortBy(field, false);
+  }
+  /** Order the page by a numeric field, largest first. */
+  sortDesc(field) {
+    return this.sortBy(field, true);
+  }
+  /**
+   * Order the page by a numeric field. Rows carrying no value for it sort last
+   * in both directions; they still count towards `totalMatches`, they simply
+   * have nothing to be ordered by.
+   */
+  sortBy(field, descending = false) {
+    if (!field.trim()) {
+      throw new PulseIndexQueryError("Sort field must not be empty.");
+    }
+    return this.fork((state) => {
+      state.sort = { field, descending };
+    });
+  }
   toRequest(defaultTenantId = "") {
-    return {
+    const request = {
       tenantId: this.state.tenantId || defaultTenantId,
       locationPrefix: this.state.locationPrefix,
       limit: this.state.limit,
@@ -489,6 +531,10 @@ var QueryBuilder = class _QueryBuilder {
       filters: this.state.filters.map((filter) => ({ ...filter })),
       ranges: this.state.ranges.map((range) => ({ ...range }))
     };
+    if (this.state.sort) {
+      request.sort = { ...this.state.sort };
+    }
+    return request;
   }
   toArray(defaultTenantId = "") {
     return this.toRequest(defaultTenantId);
@@ -535,13 +581,20 @@ var QueryBuilder = class _QueryBuilder {
     if (options.offset !== void 0) {
       query = query.offset(options.offset);
     }
+    if (options.sortBy !== void 0) {
+      query = query.sortBy(options.sortBy.field, options.sortBy.descending ?? false);
+    }
     return query;
   }
-  addFilters(op, attribute) {
+  addFilters(op, attribute, group = 0) {
     const attributes = asAttributeList(attribute);
+    const normalizedGroup = Math.max(0, Math.floor(group));
     return this.fork((state) => {
       for (const value of attributes) {
-        state.filters.push({ op, attribute: value });
+        state.filters.push({ op, attribute: value, group: normalizedGroup });
+      }
+      if (normalizedGroup >= state.nextGroup) {
+        state.nextGroup = normalizedGroup + 1;
       }
     });
   }
@@ -553,7 +606,9 @@ var QueryBuilder = class _QueryBuilder {
       limit: this.state.limit,
       offset: this.state.offset,
       filters: this.state.filters.map((filter) => ({ ...filter })),
-      ranges: this.state.ranges.map((range) => ({ ...range }))
+      ranges: this.state.ranges.map((range) => ({ ...range })),
+      sort: this.state.sort ? { ...this.state.sort } : null,
+      nextGroup: this.state.nextGroup
     };
     mutate(next.state);
     return next;
@@ -1068,6 +1123,40 @@ var PulseIndexClient = class _PulseIndexClient {
     const response = await this.delete(entityId, tenantId || this.connection.tenantId);
     return response.success;
   }
+  /**
+   * Delete many entities in one call.
+   *
+   * `delete` takes a single id, so clearing a catalogue that way is one round
+   * trip per row. Send ids in pages of up to 10,000; the engine refuses a
+   * larger batch by name rather than truncating it, so a page that is too big
+   * fails loudly instead of deleting part of itself.
+   *
+   * Ids that are unknown or already deleted are skipped, so retrying a page
+   * that half-applied is safe. `deletedCount` is the number of rows that
+   * actually changed, which is lower than `entityIds.length` whenever some of
+   * them were already gone.
+   *
+   * ```ts
+   * for (const page of pages(allIds, 10_000)) {
+   *   await client.batchDelete(page);
+   * }
+   * ```
+   */
+  async batchDelete(entityIds, tenantId) {
+    const ids = entityIds.map((id, i) => toUint64String(id, `entityIds[${i}]`));
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.batchDeleteEntities(
+        {
+          entityIds: ids,
+          tenantId: tenantId ?? this.connection.tenantId
+        },
+        metadata,
+        options,
+        callback
+      )
+    );
+    return { deletedCount: Number(raw.deletedCount ?? 0) };
+  }
   /**
    * True only when the engine can serve reads.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulseindex/sdk",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Official Node.js & TypeScript SDK for PulseIndex — hosted search and filtering for large entity sets",
   "license": "MIT",
   "author": "PulseIndex",

package/proto/engine.proto

@@ -36,6 +36,10 @@ service SearchEngineService {
   // The entity id is excluded from subsequent Search results for that tenant.
   rpc DeleteEntity (DeleteEntityRequest) returns (DeleteEntityResponse);
 
+  // BatchDeleteEntities soft-deletes many entities in one RPC.
+  // Use this to clear a catalogue: DeleteEntity takes a single id.
+  rpc BatchDeleteEntities (BatchDeleteEntitiesRequest) returns (BatchDeleteEntitiesResponse);
+
   // Search applies the boolean filters (MUST / SHOULD / MUST_NOT) plus optional
   // numeric range predicates and returns matching entity IDs only.
   // When `limit` > 0, `total_matches` may be approximate; it is exact when
@@ -114,6 +118,28 @@ message DeleteEntityResponse {
   bool success = 1;
 }
 
+// BatchDeleteEntitiesRequest deletes many entities in one tenant.
+message BatchDeleteEntitiesRequest {
+  // Entity ids to delete. Ids that are unknown or already deleted are skipped
+  // rather than refused, so retrying a batch that half-applied is safe.
+  // Repeating an id inside one batch deletes it once.
+  //
+  // A batch above the server's maximum is refused with INVALID_ARGUMENT naming
+  // the ceiling, never silently truncated.
+  repeated uint64 entity_ids = 1;
+
+  // Tenant that owns the entities. Empty → "default". One tenant per batch.
+  string tenant_id = 2;
+}
+
+// BatchDeleteEntitiesResponse reports how many rows actually changed.
+message BatchDeleteEntitiesResponse {
+  // Number of entities that were live and are now deleted. Lower than the
+  // number of ids sent when some were unknown or already deleted; that is not
+  // an error.
+  uint32 deleted_count = 1;
+}
+
 // ---------------------------------------------------------------------------
 // Search predicates
 // ---------------------------------------------------------------------------
@@ -124,7 +150,8 @@ message FilterPredicate {
   enum Operation {
     // Conjunction: narrows the current match set.
     MUST = 0;
-    // Disjunction group: SHOULD predicates are OR'd, then narrow the match set.
+    // Disjunction: SHOULD predicates sharing a `group` are OR'd together, and
+    // each group then narrows the match set.
     SHOULD = 1;
     // Exclusion: removes matches carrying this attribute.
     MUST_NOT = 2;
@@ -135,6 +162,14 @@ message FilterPredicate {
 
   // Attribute token identical to those used at index time, e.g. "feature:pool".
   string attribute = 2;
+
+  // Which disjunction this SHOULD predicate belongs to. Ignored for MUST and
+  // MUST_NOT.
+  //
+  // Members of a group are OR'd together; the groups are AND'd with each other,
+  // so "(red or blue) and (size 42 or 43)" is two groups. Predicates that leave
+  // this unset share group 0, which is the single-group behaviour.
+  uint32 group = 3;
 }
 
 // RangePredicate filters a continuous numeric field to an inclusive range.
@@ -149,6 +184,23 @@ message RangePredicate {
   uint32 max_val = 3;
 }
 
+// SortSpec orders a page by a numeric field.
+//
+// Without it, results come back in entity-id order. Entities carrying no value
+// for the field sort last in both directions; they are still counted in
+// total_matches, they simply have nothing to be ordered by.
+//
+// An ordered search cannot stop early, because the best remaining row may be
+// anywhere in the tenant, so it costs more than the same filter unordered.
+// offset + limit is capped at 100,000.
+message SortSpec {
+  // Numeric field name, the same one a RangePredicate would name.
+  string field = 1;
+
+  // Largest first when true; smallest first otherwise.
+  bool descending = 2;
+}
+
 // ---------------------------------------------------------------------------
 // Search
 // ---------------------------------------------------------------------------
@@ -167,7 +219,8 @@ message SearchQueryRequest {
   repeated RangePredicate ranges = 3;
 
   // Maximum number of entity IDs to return.
-  // 0 means no limit, and makes `total_matches` exact.
+  // 0 asks for the exact `total_matches` and no ids at all — the cheap way to
+  // count. It does not mean "no limit".
   uint32 limit = 4;
 
   // Number of matches to skip before collecting results (pagination).
@@ -175,6 +228,9 @@ message SearchQueryRequest {
 
   // Tenant / namespace to search. Empty → "default".
   string tenant_id = 6;
+
+  // Optional ordering. Absent returns matches in entity-id order.
+  SortSpec sort = 7;
 }
 
 // SearchQueryResponse returns matched ids and timing metadata.