@pulseindex/sdk 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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

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

@@ -64,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;
@@ -233,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. */
@@ -295,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.
      *
@@ -388,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, type SortSpec, 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

@@ -64,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;
@@ -233,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. */
@@ -295,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.
      *
@@ -388,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, type SortSpec, 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

@@ -1146,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

@@ -1123,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.1.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
 // ---------------------------------------------------------------------------