@twin.org/entity-storage-connector-cosmosdb 0.0.3-next.2 → 0.0.3-next.20

package/README.md

@@ -1,6 +1,6 @@
-# TWIN Entity Storage Connector Cosmos DB
+# Entity Storage Connector Cosmos DB
 
-Entity Storage connector implementation using Cosmos DB storage.
+This package provides an Azure Cosmos DB backend for globally distributed persistence across regions. It is designed to work with the wider storage ecosystem so applications can keep behaviour consistent across connectors and environments.
 
 ## Installation
 
@@ -8,24 +8,13 @@ Entity Storage connector implementation using Cosmos DB storage.
 npm install @twin.org/entity-storage-connector-cosmosdb
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of CosmosDB up and running. To run CosmosDB locally there are two possibilities:
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
 
-To run a Docker image of Azure CosmosDB:
-
-```sh
-docker run -d --platform=linux/amd64 -p 8081:8081 -m 3g --name twin-entity-storage-cosmos -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 -e AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=true -e AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE='127.0.0.1' mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
-```
-
-Or
-
-To install and run the Azure CosmosDB Emulator [Azure CosmosDB Emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-develop-emulator)
-
-Afterwards you can run the tests as follows:
-
-```sh
-npm run test
+```shell
+docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
+docker run -p 18081:8081 --detach --name twin-entity-storage-cosmos mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
 ```
 
 ## Examples

package/dist/es/cosmosDbEntityStorageConnector.js

@@ -1,9 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { CosmosClient, CosmosDbDiagnosticLevel, PartitionKeyKind } from "@azure/cosmos";
+import { BulkOperationType, CosmosClient, PartitionKeyKind } from "@azure/cosmos";
 import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
-import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, Is, ObjectHelper } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper } from "@twin.org/core";
 import { ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper, LogicalOperator, SortDirection } from "@twin.org/entity";
+import { EntityStorageHelper } from "@twin.org/entity-storage-models";
 /**
  * Class for performing entity storage operations using Cosmos DB.
  */
@@ -27,6 +28,11 @@ export class CosmosDbEntityStorageConnector {
      * @internal
      */
     static _PARTITION_KEY_VALUE = "root";
+    /**
+     * The name for the schema.
+     * @internal
+     */
+    _entitySchemaName;
     /**
      * The schema for the entity.
      * @internal
@@ -70,13 +76,16 @@ export class CosmosDbEntityStorageConnector {
         Guards.stringValue(CosmosDbEntityStorageConnector.CLASS_NAME, "options.config.databaseId", options.config.databaseId);
         Guards.stringValue(CosmosDbEntityStorageConnector.CLASS_NAME, "options.config.containerId", options.config.containerId);
         this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
+        this._entitySchemaName = options.entitySchema;
         this._partitionContextIds = options.partitionContextIds;
         this._primaryKey = EntitySchemaHelper.getPrimaryKey(this._entitySchema);
         this._config = options.config;
         this._client = new CosmosClient({
             endpoint: this._config.endpoint,
             key: this._config.key,
-            diagnosticLevel: CosmosDbDiagnosticLevel.debug
+            connectionPolicy: {
+                enableEndpointDiscovery: !this._config.disableEndpointDiscovery
+            }
         });
         this._container = this._client
             .database(this._config.databaseId)
@@ -188,6 +197,37 @@ export class CosmosDbEntityStorageConnector {
     className() {
         return CosmosDbEntityStorageConnector.CLASS_NAME;
     }
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component.
+     */
+    async health() {
+        try {
+            await this._client
+                .database(this._config.databaseId)
+                .container(this._config.containerId)
+                .read();
+            return [
+                {
+                    source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription",
+                    data: { databaseId: this._config.databaseId, containerId: this._config.containerId }
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed",
+                    data: { databaseId: this._config.databaseId, containerId: this._config.containerId }
+                }
+            ];
+        }
+    }
     /**
      * Get the schema for the entities.
      * @returns The schema for the entities.
@@ -214,9 +254,14 @@ export class CosmosDbEntityStorageConnector {
                     .read();
                 return this.itemToEntity(item);
             }
+            const conditionValues = [];
             const whereQuery = [
                 `c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionKey`
             ];
+            conditionValues.push({
+                name: "@partitionKey",
+                value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+            });
             // With a secondary index
             if (Is.stringValue(secondaryIndex)) {
                 const secIndex = secondaryIndex.toString();
@@ -225,24 +270,20 @@ export class CosmosDbEntityStorageConnector {
             else {
                 whereQuery.push(`c.${this._primaryKey.property} = @id`);
             }
+            conditionValues.push({ name: "@id", value: id });
             // With conditions
             if (Is.arrayValue(conditions)) {
                 for (const c of conditions) {
-                    const schemaProp = this._entitySchema.properties?.find(p => p.property === c.property);
-                    whereQuery.push(
-                    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-                    `c.${String(c.property)} = ${this.propertyToDbValue(c.value, schemaProp?.type)}`);
+                    whereQuery.push(`c.${c.property} = @${c.property}`);
+                    conditionValues.push({
+                        name: `@${c.property}`,
+                        value: c.value
+                    });
                 }
             }
             const query = {
                 query: `SELECT * FROM c WHERE ${whereQuery.join(" AND ")}`,
-                parameters: [
-                    { name: "@id", value: id },
-                    {
-                        name: "@partitionKey",
-                        value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
-                    }
-                ]
+                parameters: conditionValues
             };
             const { resources: items } = await this._container.items.query(query).fetchAll();
             if (items.length === 1) {
@@ -271,8 +312,10 @@ export class CosmosDbEntityStorageConnector {
         Guards.object(CosmosDbEntityStorageConnector.CLASS_NAME, "entity", entity);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
-        EntitySchemaHelper.validateEntity(entity, this.getSchema());
-        const id = entity[this._primaryKey.property];
+        const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "omit"
+        });
+        const id = prepared[this._primaryKey.property];
         try {
             if (Is.arrayValue(conditions)) {
                 const item = this._container.item(id, partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE);
@@ -284,7 +327,7 @@ export class CosmosDbEntityStorageConnector {
             await this._container.items.upsert({
                 id,
                 [CosmosDbEntityStorageConnector._PARTITION_KEY]: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
-                ...entity
+                ...prepared
             });
         }
         catch (err) {
@@ -301,6 +344,66 @@ export class CosmosDbEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(CosmosDbEntityStorageConnector.CLASS_NAME, "entities", entities);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const preparedEntities = entities.map(entity => EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "omit"
+        }));
+        try {
+            await this._container.items.executeBulkOperations(preparedEntities.map(prepared => ({
+                operationType: BulkOperationType.Upsert,
+                partitionKey: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
+                resourceBody: {
+                    id: prepared[this._primaryKey.property],
+                    [CosmosDbEntityStorageConnector._PARTITION_KEY]: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
+                    ...prepared
+                }
+            })));
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty all entities from the storage.
+     * @returns Nothing.
+     */
+    async empty() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const pk = partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE;
+        try {
+            let continuationToken;
+            do {
+                const feedOptions = { maxItemCount: 100, continuationToken };
+                const { resources, continuationToken: nextToken } = await this._container.items
+                    .query({
+                    query: `SELECT c.id FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @pk`,
+                    parameters: [{ name: "@pk", value: pk }]
+                }, feedOptions)
+                    .fetchNext();
+                continuationToken = nextToken;
+                if (Is.arrayValue(resources)) {
+                    const operations = resources.map(r => ({
+                        operationType: BulkOperationType.Delete,
+                        id: r.id,
+                        partitionKey: pk
+                    }));
+                    await this._container.items.executeBulkOperations(operations);
+                }
+            } while (Is.stringValue(continuationToken));
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
@@ -332,6 +435,66 @@ export class CosmosDbEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Remove multiple entities by id.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(CosmosDbEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const operations = ids.map(id => ({
+                operationType: BulkOperationType.Delete,
+                id,
+                partitionKey: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+            }));
+            await this._container.items.executeBulkOperations(operations);
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Teardown the storage by deleting the underlying container.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    async teardown(nodeLoggingComponentType) {
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        await nodeLogging?.log({
+            level: "info",
+            source: CosmosDbEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "containerDeleting",
+            data: { containerId: this._config.containerId }
+        });
+        try {
+            if (await this.containerExists()) {
+                await this._container.delete();
+                await this.waitForContainerNotExists();
+            }
+            await nodeLogging?.log({
+                level: "info",
+                source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "containerDeleted",
+                data: { containerId: this._config.containerId }
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "teardownFailed",
+                error: BaseError.fromError(err)
+            });
+            return false;
+        }
+    }
     /**
      * Find all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -373,7 +536,7 @@ export class CosmosDbEntityStorageConnector {
             if (queryClause.length > 0) {
                 queryClause = ` AND ${queryClause}`;
             }
-            sql = `SELECT ${properties ? properties.map(p => `c.${p}`).join(", ") : "*"} FROM c WHERE c.partitionId = @partitionId ${queryClause} ${orderByClause}`;
+            sql = `SELECT ${properties ? properties.map(p => `c.${p}`).join(", ") : "*"} FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId ${queryClause} ${orderByClause}`;
             const querySpecs = {
                 query: sql,
                 parameters: [
@@ -389,9 +552,23 @@ export class CosmosDbEntityStorageConnector {
                 continuationToken: cursor
             };
             const feedResponse = await this._container.items.query(querySpecs, feedOptions).fetchNext();
+            // CosmosDB returns a continuation token even on the last page, so peek ahead
+            // to confirm there are actually more results before exposing the cursor.
+            let resultCursor;
+            if (feedResponse.resources.length >= returnSize && feedResponse.continuationToken) {
+                const peekResponse = await this._container.items
+                    .query(querySpecs, {
+                    maxItemCount: 1,
+                    continuationToken: feedResponse.continuationToken
+                })
+                    .fetchNext();
+                if (peekResponse.resources.length > 0) {
+                    resultCursor = feedResponse.continuationToken;
+                }
+            }
             return {
                 entities: feedResponse.resources.map(i => this.itemToEntity(i)),
-                cursor: feedResponse.continuationToken
+                cursor: resultCursor
             };
         }
         catch (err) {
@@ -399,18 +576,153 @@ export class CosmosDbEntityStorageConnector {
         }
     }
     /**
-     * Delete the container.
-     * @returns Nothing.
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
      */
-    async containerDelete() {
-        const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+    async count(conditions) {
         try {
-            await this._container.deleteAllItemsForPartitionKey(partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE);
-            await this._container.delete();
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const attributeNames = {};
+            const attributeValues = {};
+            let queryClause = Is.empty(conditions)
+                ? ""
+                : this.buildQueryParameters("", conditions, attributeNames, attributeValues);
+            if (queryClause.length > 0) {
+                queryClause = ` AND ${queryClause}`;
+            }
+            const querySpec = {
+                query: `SELECT VALUE COUNT(1) FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId${queryClause}`,
+                parameters: [
+                    {
+                        name: "@partitionId",
+                        value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+                    },
+                    ...Object.keys(attributeValues).map(key => ({ name: `@${key}`, value: attributeValues[key] }))
+                ]
+            };
+            const { resources } = await this._container.items.query(querySpec).fetchAll();
+            return resources[0] ?? 0;
         }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "countFailed", undefined, err);
+        }
+    }
+    /**
+     * Get a unique list of all the context ids from the storage.
+     * @returns The list of unique context ids.
+     */
+    async getPartitionContextIds() {
+        const partitionContextIds = this._partitionContextIds;
+        if (!Is.arrayValue(partitionContextIds)) {
+            return [];
+        }
+        try {
+            const { resources: partitionIds } = await this._container.items
+                .query({
+                query: `SELECT DISTINCT VALUE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} FROM c`
+            })
+                .fetchAll();
+            return partitionIds
+                .filter(id => Is.stringValue(id))
+                .map(id => ContextIdHelper.shortSplit(partitionContextIds, id));
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "getPartitionContextIdsFailed", undefined, err);
+        }
+    }
+    /**
+     * Create the target connector for performing the migration using a temporary container.
+     * @param newEntitySchema The name of the new entity schema to create the connector for.
+     * @returns Connector for performing the migration.
+     */
+    async createTargetConnector(newEntitySchema) {
+        const migrationContainerId = `${this._config.containerId}Migration${Date.now()}`;
+        return new CosmosDbEntityStorageConnector({
+            entitySchema: newEntitySchema,
+            config: { ...this._config, containerId: migrationContainerId },
+            partitionContextIds: this._partitionContextIds
+        });
+    }
+    /**
+     * Finalize the migration by tearing down the old container and replacing it with the target container.
+     * @param targetConnector The target connector to finalize the migration with.
+     * @param options The options to control how the migration is finalized.
+     * @param loggingComponentType The optional component type to use for logging.
+     * @returns The final connector pointing at the original container id.
+     */
+    async finalizeMigration(targetConnector, options, loggingComponentType) {
+        // There is no rename operation in DynamoDB so we have to create a new table with the original name and copy the data over
+        // Teardown the existing table with the original name to free up the name for the new table
+        await this.teardown(loggingComponentType);
+        // Create a new connector with the original table name but with the new schema
+        // and copy the data from the migration table to the new table using batch operations
+        const finalConnector = new CosmosDbEntityStorageConnector({
+            entitySchema: targetConnector._entitySchemaName,
+            config: this._config,
+            partitionContextIds: this._partitionContextIds
+        });
+        if (await finalConnector.bootstrap(loggingComponentType)) {
+            // Since there is no rename, we need to copy the data from the migration table to the new table
+            const partitions = await targetConnector.getPartitionContextIds();
+            const batchSize = options?.batchSize ?? CosmosDbEntityStorageConnector._DEFAULT_LIMIT;
+            await this.bulkCopy(targetConnector, finalConnector, partitions, batchSize);
+            await targetConnector.teardown(loggingComponentType);
+            return finalConnector;
+        }
+        throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "finalizeMigrationFailedBootstrap");
+    }
+    /**
+     * Cleanup the migration if a migration fails or needs to be aborted.
+     * @param targetConnector The target connector to cleanup.
+     * @param options The options to control how the migration is cleaned up.
+     * @param loggingComponentType The optional component type to use for logging.
+     */
+    async cleanupMigration(targetConnector, options, loggingComponentType) {
+        // If something failed the only thing to cleanup is the migration table
+        await targetConnector?.teardown?.(loggingComponentType);
+    }
+    /**
+     * Copy all entities from sourceConnector to destConnector, paging through each partition.
+     * @param sourceConnector The connector to read entities from.
+     * @param destConnector The connector to write entities to.
+     * @param partitions The partition list returned by getPartitionContextIds.
+     * @param batchSize The number of entities to read per page.
+     * @internal
+     */
+    async bulkCopy(sourceConnector, destConnector, partitions, batchSize) {
+        let partitionList;
+        if (Is.arrayValue(partitions)) {
+            partitionList = partitions;
+        }
+        else if (Is.arrayValue(sourceConnector._partitionContextIds)) {
+            partitionList = [];
+        }
+        else {
+            partitionList = [{}];
+        }
+        for (let i = 0; i < partitionList.length; i++) {
+            const partitionKey = ContextIdHelper.combinedContextKey(partitionList[i], sourceConnector._partitionContextIds) ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE;
+            let continuationToken;
+            do {
+                const feedOptions = { maxItemCount: batchSize, continuationToken };
+                const { resources, continuationToken: nextToken } = await sourceConnector._container.items
+                    .query({
+                    query: `SELECT * FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId`,
+                    parameters: [{ name: "@partitionId", value: partitionKey }]
+                }, feedOptions)
+                    .fetchNext();
+                continuationToken = nextToken;
+                if (Is.arrayValue(resources)) {
+                    const operations = resources.map(({ _rid: rid, _self: self, _ts: ts, _etag: etag, _attachments: attachments, ...rest }) => ({
+                        operationType: BulkOperationType.Upsert,
+                        partitionKey,
+                        resourceBody: rest
+                    }));
+                    await destConnector._container.items.executeBulkOperations(operations);
+                }
+            } while (Is.stringValue(continuationToken));
         }
     }
     /**
@@ -463,7 +775,18 @@ export class CosmosDbEntityStorageConnector {
         prop += comparator.property;
         let attributeName = this.populateAttributeNames(prop, attributeNames);
         let propName = `${attributeName.replace(/\./g, "").replace(/@/g, "")}`;
-        if (Is.array(comparator.value)) {
+        if ((comparator.comparison === ComparisonOperator.Equals ||
+            comparator.comparison === ComparisonOperator.NotEquals) &&
+            (comparator.value === null || comparator.value === undefined)) {
+            // Cosmos DB SQL null semantics mirror standard SQL: any comparison using = or <>
+            // against null evaluates to UNKNOWN, not TRUE, so no rows are returned.
+            // IS_NULL() and IS_DEFINED() must be used instead (no bound parameter needed).
+            if (comparator.comparison === ComparisonOperator.Equals) {
+                return `(IS_NULL(c.${attributeName}) OR NOT IS_DEFINED(c.${attributeName}))`;
+            }
+            return `(IS_DEFINED(c.${attributeName}) AND NOT IS_NULL(c.${attributeName}))`;
+        }
+        else if (Is.array(comparator.value)) {
             const dbValues = comparator.value.map(v => this.propertyToDbValue(v, type));
             const arrAttributeNames = [];
             for (let i = 0; i < dbValues.length; i++) {
@@ -474,7 +797,27 @@ export class CosmosDbEntityStorageConnector {
             propName = attributeName;
             attributeName = `(${arrAttributeNames.map(name => `@${name}`).join(", ")})`;
         }
+        else if (Is.object(comparator.value) &&
+            (comparator.comparison === ComparisonOperator.Equals ||
+                comparator.comparison === ComparisonOperator.NotEquals)) {
+            // CosmosDB SQL does not support object equality with =; expand to per-property comparisons.
+            const op = comparator.comparison === ComparisonOperator.Equals ? "=" : "<>";
+            const join = comparator.comparison === ComparisonOperator.Equals ? " AND " : " OR ";
+            const clauses = [];
+            for (const [key, val] of Object.entries(comparator.value)) {
+                const paramName = `${propName}${key}`;
+                attributeValues[paramName] = val;
+                clauses.push(`c.${attributeName}.${key} ${op} @${paramName}`);
+            }
+            return clauses.length === 1 ? clauses[0] : `(${clauses.join(join)})`;
+        }
         else {
+            // Avoid parameter name conflicts by ensuring unique parameter names in the query
+            let counter = 1;
+            while (propName in attributeValues) {
+                propName = `${attributeName.replace(/\./g, "").replace(/@/g, "")}${counter}`;
+                counter++;
+            }
             attributeValues[propName] = comparator.value;
         }
         const matches = attributeName.split(".").length;
@@ -505,13 +848,13 @@ export class CosmosDbEntityStorageConnector {
         }
         else if (typeof attributeValues[propName] === "object" &&
             comparator.comparison === ComparisonOperator.Includes) {
-            return `array_contains(c.${attributeName}, @${propName})`;
+            return `ARRAY_CONTAINS(c.${attributeName}, @${propName}, true)`;
         }
         else if (comparator.comparison === ComparisonOperator.Includes) {
-            return `contains(c.${attributeName}, @${propName})`;
+            return `CONTAINS(c.${attributeName}, @${propName})`;
         }
         else if (comparator.comparison === ComparisonOperator.NotIncludes) {
-            return `notContains(c.${attributeName}, @${propName})`;
+            return `NOT CONTAINS(c.${attributeName}, @${propName})`;
         }
         else if (comparator.comparison === ComparisonOperator.In) {
             return `c.${propName} IN ${attributeName}`;
@@ -598,13 +941,14 @@ export class CosmosDbEntityStorageConnector {
      * @internal
      */
     itemToEntity(item) {
-        ObjectHelper.propertyDelete(item, "partitionId");
-        ObjectHelper.propertyDelete(item, "_attachments");
-        ObjectHelper.propertyDelete(item, "_etag");
-        ObjectHelper.propertyDelete(item, "_rid");
-        ObjectHelper.propertyDelete(item, "_self");
-        ObjectHelper.propertyDelete(item, "_ts");
-        return item;
+        return EntityStorageHelper.unPrepareEntity(item, [
+            CosmosDbEntityStorageConnector._PARTITION_KEY,
+            "_attachments",
+            "_etag",
+            "_rid",
+            "_self",
+            "_ts"
+        ]);
     }
     /**
      * Check if the database exists.
@@ -665,5 +1009,19 @@ export class CosmosDbEntityStorageConnector {
             await new Promise(resolve => setTimeout(resolve, 250));
         }
     }
+    /**
+     * Wait for a container to not exist.
+     * @returns Nothing.
+     * @internal
+     */
+    async waitForContainerNotExists() {
+        for (let attempt = 0; attempt < 20; attempt++) {
+            const containerExists = await this.containerExists();
+            if (!containerExists) {
+                break;
+            }
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+    }
 }
 //# sourceMappingURL=cosmosDbEntityStorageConnector.js.map