How to create catalogs
How to create catalogs
To manage catalogs, add the data-client module as a dependency to your
project.
Configure catalogs
Catalog configurations include the properties listed in the following table. Mandatory properties are in bold.
NoteCatalog IDs
Catalog IDs are publicly visible since they are part of the catalog HRN. Do not include private or company confidential information when you specify a catalog ID. Catalog names are private by default, which means you can add your private or confidential information in this field.
| Property | Description |
|---|---|
| id | IDs are part of the HERE Resource Name (HRN) for a catalog. |
| name | A short-form name for the catalog. |
| summary | A one sentence summary describing the catalog. This summary is visible when you browse a list of catalogs on the platform portal. |
| description | A detailed description of the catalog and its content. This information appears on the 'Overview' tab when you open a catalog in the platform portal. |
| layers | The layers in the catalog. |
| tags | Some keywords that help when searching for the catalog in the platform portal. |
| notificationsEnabled | If enabled, a notification topic for the catalog is created. This topic allows an application to receive a notification when the catalog is updated. |
| automaticVersionDeletion | If set, enables automatic deletion of catalog versions to manage storage costs and enable lifecycle management of versioned layers. |
| areaScheme | The HERE Resource Name (HRN) of the area scheme used across the catalog. If the value is not set than no area scheme is applied to the catalog. |
| subsetRestrictions | Indicates if the subsetRestrictions for a catalog is enabled or not. subsetRestrictions can only be enabled for catalogs that are defined within projects. It requires area scheme being set. If catalog subsetRestrictions are disabled, supported layer's subsetRestrictions will be disabled by default. |
Layer configurations include the properties listed in the table below.
| Property | Description |
|---|---|
| id | IDs must be unique for all layers within a catalog. |
| name | A short-form name for the layer. |
| summary | A one sentence summary describing the layer. This summary is visible when you browse a list of layers on the platform portal. |
| description | A detailed description of the layer and its contents. This information appears on the 'Overview' tab when you open a layer in the platform portal. |
| layerType | The type of data provided by the layer: versioned, volatile, stream, index, interactivemap or objectstore. |
| volumeType | Properties that describe the volume where the data is physically stored: durable or volatile. |
| partitioning | The name of the partitioning scheme for this layer: generic or heretile. This property is not supported by the objectstore layer type. |
| contentType | The MIME type of the data stored in the layer. This property is not supported by the object store layer type. |
| contentEncoding | Indicator if the data is compressed. Currently, gzip is supported. |
| coverage | A set of admin area strings ( ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL' or 'CN-HK'), which define the geographic area that this layer covers. |
| tags | A list of keywords that help to find the layer when searching in the platform portal. |
| billing tags | A list of billing tags a free-form tag, which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9]. |
| schema | The HRN of the data schema for this layer. |
| digest | The digest algorithm used by the data publisher to generate a checksum for each partition in the layer. Data consumers can use it to verify the integrity of the data they retrieve from the layer. Currently, MD5, SHA-1 and SHA-256 are supported. |
| crc | The CRC algorithm used to calculate the checksum for the partitions in this layer. Currently, CRC-32C is supported. |
Versioned layer configuration
Versioned layers have the following additional configuration fields.
| Property | Description |
|---|---|
| secureHandles | A boolean flag which indicates if the layer metadata and blob are in mode of secure data handles support. It requires catalog area scheme to be set and supports only heretile partitioning of the layer. |
| subsetRestrictions | A boolean flag which indicates if the subsetRestrictions for a layer is enabled or not. subsetRestrictions can only be enabled for layers of catalogs that are defined within projects. It requires area scheme of the catalog being set. Supported layer subsetRestrictions are enabled by default when subsetRestrictions is enabled for the catalog. Layer subsetRestrictions requires catalog subsetRestrictions to be enabled. If catalog subsetRestrictions are disabled, supported layer's subsetRestrictions will be disabled by default. Supported only for layers with heretile partitioning. |
Volatile layer configuration
Volatile layers have the following additional configuration fields.
| Property | Description |
|---|---|
| ttl | The expiry time in milliseconds for data in this layer. Data is automatically removed after the specified time limit has elapsed. For volatile layers the TTL value must be between 60000 (1 minute) and 604800000 (7 days). |
| dataRedundancy | The data redundancy for volatile layers. Possible enum values are single-instance or multi-instance. Single instance layers do not have data redundancy, whereas multi instance layers do. |
| storageCapacityMb | The storage capacity of the layer specified in megabytes, with an increment step of 100 (eg. 100, 500, 600, 2000). For volatile layers, the storage capacity must be between 100 (100MB) and 21000 (21GB). |
| secureHandles | A boolean flag which indicates if the layer metadata and blob are in mode of secure data handles support. It requires catalog area scheme to be set and supports only heretile partitioning of the layer. |
| subsetRestrictions | A boolean flag which indicates if the subsetRestrictions for a layer is enabled or not. subsetRestrictions can only be enabled for layers of catalogs that are defined within projects. It requires area scheme of the catalog being set. Supported layer subsetRestrictions are enabled by default when subsetRestrictions is enabled for the catalog. Layer subsetRestrictions requires catalog subsetRestrictions to be enabled. If catalog subsetRestrictions are disabled, supported layer's subsetRestrictions will be disabled by default. Supported only for layers with heretile partitioning. |
Index layer configuration
Index layers have the following additional configuration fields.
| Property | Description |
|---|---|
| indexDefinitions | The collection of index key definitions to index published partitions. |
| ttl | Time to Live of indexed data in index layer. If not specified it defaults to 7 days. |
Each index key definition contains the following configuration fields:
| Property | Description |
|---|---|
| name | The name of index key. Max name length is 64 characters. The name must begin with a Unicode letter. Subsequent characters can be letters, underscores (_), digits (0-9) |
| indexType | The type of index key. Supported types: Int, Bool, String, TimeWindow, and HereTile. |
| duration | Duration attribute of the TimeWindow type must be in the range 600000 (10 minutes) .. 86400000 (24h in millis) |
| zoomLevel | zoomLevel attribute for HereTile type must be in 0 .. 14 range |
Supported index key types:
| Property | Description |
|---|---|
| Int | A signed integer, up to 64 bits. |
| Bool | A Boolean value. |
| String | A string of Unicode characters with the maximum length of 40. |
| TimeWindow | Represents the time slice (NOT just point in time) and it denotes the finest time granularity at which the data will be indexed and later queried. Time type has an attribute duration which represents the time slice length and similarly to the here-tile is NOT mutable. Both here-time value and here-time duration attribute is expressed in milliseconds (time value is milliseconds since Epoch). |
| HereTile | Represents the tile id in the HERE tile map tiling scheme. HereTile type has an attribute zoomLevel which represents the size of the tile and it's NOT mutable. |
The TimeWindow index key is required. Index layers can have at most a single TimeWindow and a single HereTile index key. This means that Index layers can have exactly one TimeWindow index key and only one optional HereTile index key.
Below are the possible TTL values:
| Enum Value | TTL |
|---|---|
| SevenDays | 7 days |
| FifteenDays | 15 days |
| OneMonth | 30 days |
| TwoMonths | 60 days |
| ThreeMonths | 90 days |
| FourMonths | 120 days |
| SixMonths | 180 days |
| OneYear | 365 days |
| OneAndHalfYears | 548 days |
| TwoYears | 730 days |
| Unlimited | unlimited |
Stream layer configuration
Stream layers have the following additional configuration fields.
| Property | Description |
|---|---|
| dataInThroughputKbps | Maximum throughput for incoming data expressed in kilobytes per second. Throttling occurs when the inbound rate exceeds the maximum inbound throughput. The default is 1000 KBps. The minimum is 100 KBps, the maximum is 32800 KBps. Can only be multiple of 100 KBps. |
| dataOutThroughputKbps | Maximum throughput for outgoing data expressed in kilobytes per second. Throttling occurs when the total outbound rate to all consumers exceeds the maximum outbound throughput. The default is 4000 KBps. The minimum is 100 KBps, the maximum is 65500 KBps. Can only be multiple of 100 KBps. |
| parallelization | The number of Kafka partitions for Stream Layer. The default is 4, the maximum is 32. |
| ttl | The expiry time in milliseconds for data in this layer. Data is automatically removed after the specified time limit has elapsed. For stream layers, the TTL value must be between 600000 (10 minutes) and 259200000 (72 hours). |
NoteGeneral recommendation for stream layer properties
(dataInThroughputKbpsanddataOutThroughputKbpsandparallelization) is to provide all of them in the request.To preserve backward compatibility, there are few corner cases:
- User should provide either
dataInThroughputKbpsanddataOutThroughputKbpsorparallelization.- If all 3 fields are provided, then we use them as is.
- If all stream properties are missing, then default values
dataInThroughputKbps = 1000, dataOutThroughputKbps = 4000, parallelization = 4will be set
Interactive Map layer configuration
Interactive Map layers have the following additional configuration fields.
| Property | Description |
|---|---|
| Searchable Properties | Interactive map layers can be configured with 'Searchable Properties'. This is a list of strings containing the properties you want to index for faster searching. Searchable properties can be updated at any time. A maximum of eight searchable properties can be added. |
Automatic version deletion configuration
WarningData loss
Deleting Catalog versions will delete partition metadata AND data associated with those versions, impacting all versioned layers in the catalog. The partition metadata and data will be irrecoverable. Any partition metadata and data from deleted versions that is still used in current, non-deleted versions will not be deleted so that non-deleted versions remain functional.
Supported automaticVersionDeletion types:
| Property | Description |
|---|---|
| numberOfVersionsToKeep | If set and once the max number of versions is reached, every time a new version is created, the oldest version will be deleted. |
NoteFor instructions on how to disable automatic version deletion, see Disable an Automatic Version Deletion
Create catalogs
To configure and create catalogs, add the following:
val catalogId = "creating-catalog-test-" + someIdentifierSuffix
val catalogConfig =
WritableCatalogConfiguration(
id = catalogId,
name = catalogId,
summary = "This is a catalog summary.",
description = "This is what the catalog is for.",
tags = Set("tag1", "tag2", "tag3"),
automaticVersionDeletion =
Some(AutomaticVersionDeletion.builder.withNumberOfVersionsToKeep(10L).build),
areaScheme = Some(HRN.fromString("hrn:here:areascheme::olp-here:default-countries")),
subsetRestrictions = Some(true),
layers = Seq(
WritableLayer(
id = "layer-0",
name = "INFO",
summary = "This is a layer summary.",
description = "This is a layer description.",
layerType = VersionedLayerType(),
partitioning = GenericPartitioning,
volume = Volumes.Durable,
contentType = "application/x-protobuf",
digest = Some(DigestAlgorithm.MD5),
crc = Some(CrcAlgorithm.CRC32C)
),
WritableLayer(
id = "layer-1",
name = "SCHEMAS",
summary = "This is a layer summary.",
description = "This is a layer description.",
layerType = VersionedLayerType(),
partitioning = GenericPartitioning,
volume = Volumes.Durable,
contentType = "application/x-protobuf"
),
WritableLayer(
id = "layer-2",
name = "VOLATILEDATA",
summary = "This is a layer summary.",
description = "This is a layer description.",
layerType =
VolatileLayerType(secureHandles = Some(true), subsetRestrictions = Some(true)),
partitioning = HereTilePartitioning(tileLevels = 1 :: Nil),
volume = Volumes.Durable,
contentType = "application/octet-stream",
contentEncoding = Some(ContentEncoding.gzip),
coverage = Some(Coverage(Set[String]("DE", "US")))
),
WritableLayer(
id = "layer-3",
name = "INDEX",
summary = "This is a layer summary.",
description = "This is a layer description.",
layerType = IndexLayerType(
indexDefinitions = Seq(
IndexDefinition("someIntKey", IndexType.Int),
IndexDefinition("someStringKey", IndexType.String),
IndexDefinition("someTimeWindowKey",
IndexType.TimeWindow,
duration = Some(3600000)),
IndexDefinition("someHereTileKey", IndexType.HereTile, zoomLevel = Some(8))
),
ttl = Ttl.OneMonth
),
partitioning = NoPartitioning,
volume = Volumes.Durable,
contentType = "application/octet-stream",
digest = Some(DigestAlgorithm.SHA256),
crc = Some(CrcAlgorithm.CRC32C)
),
WritableLayer(
id = "layer-4",
name = "OBJECTSTORE",
summary = "This is layer summary",
description = "This is layer description",
layerType = ObjectStoreLayerType(),
partitioning = NoPartitioning,
volume = Volumes.Durable
),
WritableLayer(
id = "layer-5",
name = "INTERACTIVEMAP",
summary = "This is layer summary",
description = "This is layer description",
layerType = InteractiveMapLayerType(
interactiveMapProperties = Some(
InteractiveMapProperties(searchableProperties = Seq("abc"),
versionsToKeep = Some(123L)))
),
partitioning = NoPartitioning,
volume = Volumes.Durable
)
)
)
val adminApi = DataClient().adminApi()
adminApi.createCatalog(catalogConfig).flatMap { hrn =>
log.info(s"Created new catalog `$hrn`")
processCreatedCatalog(hrn)
}String catalogId = "creating-catalog-test-" + someIdentifierSuffix;
WritableCatalogConfiguration catalogConfig =
new WritableCatalogConfiguration.Builder()
.withId(catalogId)
.withName(catalogId)
.withSummary("This is a catalog summary.")
.withDescription("This is what the catalog is for.")
.withTags(new HashSet<>(Arrays.asList("tag1", "tag2", "tag3")))
.withAutomaticVersionDeletion(
AutomaticVersionDeletion.builder().withNumberOfVersionsToKeep(10L).build())
.withLayers(
Arrays.asList(
new WritableLayer.Builder()
.withId("layer-0")
.withName("INFO")
.withSummary("This is a layer summary.")
.withDescription("This is a layer description.")
.withLayerType(VersionedLayerType.defaultInstance())
.withPartitioning(Partitioning.Generic())
.withVolume(Volumes.Durable())
.withContentType("application/x-protobuf")
.withDigest(DigestAlgorithm.SHA256())
.withCrc(CrcAlgorithm.CRC32C()),
new WritableLayer.Builder()
.withId("layer-1")
.withName("SCHEMAS")
.withSummary("This is a layer summary.")
.withDescription("This is a layer description.")
.withLayerType(VersionedLayerType.defaultInstance())
.withPartitioning(Partitioning.Generic())
.withVolume(Volumes.Durable())
.withContentType("application/x-protobuf"),
new WritableLayer.Builder()
.withId("layer-2")
.withName("INDEX")
.withSummary("This is a layer summary.")
.withDescription("This is a layer description.")
.withLayerType(
new IndexLayerType.Builder()
.addIndexDefinition(
new IndexDefinition.Builder()
.withName("someIntKey")
.withIndexType(IndexType.Int)
.build())
.addIndexDefinition(
new IndexDefinition.Builder()
.withName("someStringKey")
.withIndexType(IndexType.String)
.build())
.addIndexDefinition(
new IndexDefinition.Builder()
.withName("someTimeWindowKey")
.withIndexType(IndexType.TimeWindow)
.withDuration(3600000L)
.build())
.addIndexDefinition(
new IndexDefinition.Builder()
.withName("someHereTileKey")
.withIndexType(IndexType.HereTile)
.withZoomLevel(8)
.build())
.withTtl(Ttl.OneMonth)
.build())
.withPartitioning(Partitioning.NoPartition())
.withVolume(Volumes.Durable())
.withContentType("application/x-protobuf"),
new WritableLayer.Builder()
.withId("layer-3")
.withName("OBJECTSTORE")
.withSummary("This is layer summary")
.withDescription("This is layer description")
.withLayerType(ObjectStoreLayerType.defaultInstance())
.withPartitioning(Partitioning.NoPartition())
.withVolume(Volumes.Durable()),
new WritableLayer.Builder()
.withId("layer-4")
.withName("INTERACTIVEMAP")
.withSummary("This is layer summary")
.withDescription("This is layer description")
.withLayerType(
new InteractiveMapLayerType.Builder()
.withInteractiveMapProperties(
new InteractiveMapProperties.Builder()
.withSearchableProperties(
Arrays.asList("some-property1", "some-property-2"))
.build())
.build())
.withPartitioning(Partitioning.NoPartition())
.withVolume(Volumes.Durable())
.withContentType("application/geo+json")))
.build();
AdminApi adminApi = DataClient.get(myActorSystem).adminApi();
adminApi
.createCatalog(catalogConfig)
.thenApply(
hrn -> {
log.info("Created new catalog `" + hrn + "`");
return processCreatedCatalog(hrn);
});
NoteIt may take several minutes for a new catalog to appear in the list of catalogs returned by the Data Client Library, CLI, REST API, and the list displayed on the HERE platform portal.
Updated 21 days ago