Microsoft Azure Cosmos DB Writer Feature Type Parameters

To access feature type parameters, click the gear icon on a feature type in the workspace. This opens the Feature Type Parameter Editor.

Tip  To always display the editor in FME Workbench, you can select View > Windows > Parameter Editor.

General

All feature types share similar General parameters, which may include Feature Type Name, Reader or Writer information, and Geometry.

In most Writer Feature Type parameter dialogs, you can also control Dynamic Schema Definitions. Some database formats accept Table or Index Qualifier prefixes on the output table feature type.

Important  These parameters apply only to a selected feature type, not to the entire writer. If a feature type parameter listed here conflicts with a writer-level parameter, then the writer parameter will be ignored and this feature type parameter will be used.

Collection Settings

This parameter specifies the type of write operation to perform for incoming features.

All operations require a value for the id property. The attribute to use as the source of id values can be configured by the Document ID Attribute writer feature type parameter.

Feature Operation fme_db_operation

Description
Insert INSERT

Insert Document – If a Document already exists with the same id, a warning is logged, and the feature is skipped.
Upsert UPSERT

Upsert Document – If a Document already exists with the same id, it is replaced. Otherwise, a new Document is created.
Replace DELSERT

Replace Document – If there is no existing Document with the same id, a warning is logged, and the feature is skipped.
Delete DELETE

Delete Document – If there’s no existing Document with the specified id, a warning is logged, and the feature is skipped.
fme_db_operation   Use the Feature Operation specified in the fme_db_operation attribute for each feature. If a feature has no value for fme_db_operation, it is treated as INSERT.

This parameter specifies the behavior around Collection (Feature Type) creation. The possible values are:

  • Use Existing (default) – If the Feature Type name doesn’t match the id of an existing Collection, an error is raised.
  • Create If Needed – If the Feature Type name doesn’t match the id of an existing Collection, then create a Collection with id as the Feature Type name.
  • Drop and Create – If the Feature type name matches the id of an existing Collection, delete the Collection, and create a new Collection with the same id. You cannot use the Cosmos DB writer to delete a Collection without also re-creating it.
Warning  Any customizations to the Collection made outside of the Cosmos DB writer will be lost.

If the writer creates the Collection, it will configure the Collection with this provisioned capacity, in Request Units per second (RU/s).

This optional parameter corresponds to the x-ms-offer-throughput header. If specified, the value must be at least 400, in increments of 100. The upper bound may vary depending on your Account.

Note  Collections created by the Cosmos DB writer use default settings, so it is not possible to configure the indexing policies, triggers, stored procedures, and user-defined functions via the Cosmos DB writer.

Warning  Since there is an hourly cost associated with each Collection, use caution to avoid creating too many Collections. To avoid unintended creation of Collections, the default setting for this parameter is Use Existing. Writer Feature Types should be imported from the Cosmos DB reader to avoid defining Feature Types that do not correspond to an existing Collection, and potentially triggering the unintended creation of a Collection. (By default, when the writer is added to the workspace, the Collection Definition is set to Copy from Reader.)

Advanced

The source of JSON documents to write to the database:

  • Feature: – A Document is assembled for each incoming feature based on the writer feature type schema. Each attribute on the schema corresponds to a top-level property on the generated Document.
  • JSON Attribute – Documents are obtained from an attribute containing the complete JSON Document.

This optional parameter appears when Document Source is set to Feature.

This parameter specifies an attribute that contains the value of the id property for Documents. A GUID is generated and used for the id property if:

  • This parameter is not specified.
  • This parameter is specified, but the feature does not have a value for the corresponding attribute.

When publishing to the server, the value of this attribute gets reassigned to the key id.

For Replace and Delete operations, this parameter must be specified, and all features must provide a value for the corresponding attribute.

This parameter appears when Document Source is set to JSON Attribute.

This parameter specifies the attribute that contains the complete JSON for a Document. All features must provide a valid JSON Document in the feature. The writer will warn and reject features with invalid JSON, or JSON missing the id property.

Document Options

If this optional parameter is specified, and the feature being written has geometry, the Cosmos DB writer will convert the geometry to GeoJSON and write it out under the specified property.

The resulting GeoJSON overwrites the value that may be present under any user attribute with the same name as this parameter.

Default: geom

This required parameter serves a dual purpose.

When the writer creates a Collection, this parameter is used to define the Partition Key for the Collection. In this scenario, the parameter is prefixed with “/” if necessary.

When the writer writes a feature (Document), this parameter is used to specify the attribute that contains the Partition Key. To specify an attribute within a nested object, use standard path notation (/). The writer takes the value for the specified attribute, converts it to JSON array with a single string element, and includes it as the value of the x-ms-documentdb-partitionkey header.

For more information on Partition Keys, see Choose a partition key in Microsoft Azure Cosmos DB documentation.