The Azure Cosmos DB data source type in ArcGIS Velocity reads records from database collections stored in Azure Cosmos DB.
Example
A researcher wants to load data from a database collection stored in Azure Cosmos DB into Velocity to perform analysis.
Usage notes
Keep the following in mind when working with the Azure Cosmos DB source:
- The master key is encrypted the first time the analytic is saved and is stored in an encrypted state.
- A where clause can be specified to restrict the records loaded from the Azure Cosmos DB container collection.
- Analytic run time variables can be specified in the Where clause parameter to only load new features from the Azure Cosmos DB container collection for each run.
Parameters
The following are the parameters for the Azure Cosmos DB source:
| Parameter | Description | Data type |
|---|---|---|
Endpoint | The endpoint URL for Azure Cosmos DB, for example, https://yourCosmosDBAccountName.documents.azure.com:443/. | String |
Master key | The primary key for Azure Cosmos DB. | String |
Database | The name of the Azure Cosmos DB container that contains the collection of data to read. | String |
Collection | The name of the Azure Cosmos DB collection in the specified container that contains the data. | String |
Where clause (optional) | Restrict the features loaded from the Azure Cosmos DB container collection. Use a simple query format. For example, if a numeric field named course exists in the dataset, you can specify a where clause of course = 49.5845184; if a string field named user_id exists in the dataset, you can specify a where clause of user_id = 'pete1234'. In the Azure Cosmos DB interface, these queries are in the form SELECT * FROM c WHERE c.user_id = 'pete1234'; however, you must specify user_id = 'pete1234' for this parameter in Velocity. When querying string fields, use single quotation marks around text that is part of the query, for example, road_type = 'asphalt'. Analytic run time variables can be specified to only load new features for each run in a recurring big data analytic. These variables are replaced with the relevant analytic scheduled start times for querying ISO 8601 string fields in Azure Cosmos DB. The available analytic run time variables available are $analytic.AnalyticLastSuccessfulRunScheduledStartTime and $analytic.AnalyticScheduledStartTime. For the first run after starting a scheduled big data analytic, the $feature.AnalyticLastSuccessfulRunScheduledStartTime variable is provided as the ISO 8601 origin time of January 1, 1970, so all features after this time will be loaded. To accommodate this, specify an additional part of the where clause query to return features after the anticipated first run time of the recurring analytic. For example, you can specify a where clause as shown below in which the analytic was started June 6, 2021, at 12:01:01 UTC. yourISO8601StringTimestampField > '$analytic.AnalyticLastSuccessfulRunScheduledStartTime' and yourISO8601StringTimestampField <= '$analytic.AnalyticScheduledStartTime' and yourISO8601StringTimestampField > '2021-06-04T12:01:01.0Z' | String |
Considerations and limitations
The following are considerations and limitations when using the Azure Cosmos DB source:
- When specifying a where clause to filter string values, wrap text values in single quotation marks.
- When specifying date fields, only the following configurations are supported for this data source:
- Epoch seconds such as 1616673883
- Epoch milliseconds such as 1616673883000
- ISO 8601 datetime format with no time zone such as 2021-03-25T12:05:34
- ISO 8601 datetime format with a time zone such as 2021-03-25T12:05:34+0000
- String dates in the format (milliseconds are optional) yyyy-MM-dd HH:mm:ss[.fffffffff] such as 2021-03-25 12:05:34 or 2021-03-25 12:05:34.435