Structure of a generator assignment

In the Tonic Structural API, a generator assignment is referred to as a replacement.

A group of replacements makes up the message body for the response to get generator configuration details, and a request to update generator configuration details.

For details and examples of replacements for each Structural generator, go to Generator API reference.

Replacement structure

At a very high level, the structure of a replacement object is:

Diagram showing the overall outline of the replacement structure

Each Replacement object contains:

• The name of the replacement

• The schema and table where the configured columns are located

• Link objects for generator and sub-generator configurations

• Columns to use for partitioning

• Model configuration for the AI Synthesizer

Link object structure

Within a replacement, each link object contains the generator or sub-generator configuration for a single column.

For fallBackLinks, the link object contains the generator configuration for the fallback generator.

{
  "schema": "string",
  "table": "string",
  "column": "string",
  "dataType": "string",
  "metadata": {
    "presetId": "string",
    "generatorId": "string",
    "isConsistent": boolean,
    "consistencyColumn": "string",
    "isDifferentiallyPrivate": boolean,
    //Other generator configuration fields
    "encryptionProcessor": "x-on", //To use configured Structural data encryption
    "customValueProcessor": "string", //If custom value processor applied
    "pathExpression": "string", //Path expression for a composite generator
    "subGeneratorMetadata": {
      "presetId": "string",
      "generatorId": "string",
      "customValueProcessor": "string" //If custom value processor applied to the sub-generator
      //Other generator configuration fields for the sub-generator
    }
  }
}

Column identification

In the link object, to identify the column, you provide the schema name, table name, and column name.

The schema and table values in the link object must match the schema and table values for the replacement.

For MongoDB, you also provide the data type.

Note that even if there isn't a schema (for example, for the Databricks data connector), you must still provide an empty value for schema.

Metadata

In the link object, the metadata object identifies the generator and generator preset, and provides the generator configuration.

Generator and preset identification

In the metadata object, presetId identifies the applied generator preset configuration. generatorId identifies the type of generator. generatorId must match the generator type for presetId.

Generator presets require an Enterprise license. For Basic and Professional licenses, only generatorId is provided.

For the built-in preset for a generator, presetId and generatorId are the same. If during configuration the generator preset specified by presetId is not available - for example, if the generator preset was deleted - then the baseline version of the generator specified by generatorId is applied.

Generator configuration

For the generator configuration, metadata contains fields from BaseMetadata, which provides the fields to configure consistency and differential privacy.

metadata can also contain additional objects and fields from generator-specific metadata objects.

Structural data encryption

In the metadata object, if Structural data encryption is enabled for the instance, then to indicate to use the configured data encryption, set encryptionProcessor to x-on.

Custom value processors

In the metadata object, you can specify a custom value processor to apply to the generator (customValueProcessor).

Sub-generator configuration

In the metadata object, for composite generators other than Array Regex, Regex, or Conditional, pathExpression identifies the value within the column to apply a sub-generator to.

The subGeneratorMetadata object then identifies and configures the generator to apply to that value:

"pathExpression": "string",
"subGeneratorMetadata": {
  "presetId": "string",
  "generatorId": "string",
  "customValueProcessor": "string"
   //Other generator configuration fields for the sub-generator
}

Within subGeneratorMetadata:

• presetId identifies the generator preset to apply.

• generatorId identifies the type of generator.

• customValueProcessor identifies the custom value processor to apply.

subGeneratorMetadata also contains any other fields used to configure the selected sub-generator.

Partition column list

The Continuous and Event Timestamps generators allow partitioning.

In the replacement object, the partitions field contains a comma-separated list of columns to partition by.

AI Synthesizer model configuration

In the replacement object, the NnModelConfig object is used for the AI Synthesizer. It provides the model configuration.

modelType indicates whether the model contains event data. If the model contains event data, modelType is RNN_VAE. If the model does not contain model data, modelType is VAE.

Several configuration fields apply to both types of models. Other fields are specific to one type of model.

For models that contain event data, the nnModelConfig structure is:

"nnModelConfig": {
  "modelType": "enum",
  "epochs": integer,
  "batchSize": integer,
  "earlyStopping": boolean,
  "recLossFactor": integer,
  "latentDim": integer,
  "maxCategoricalDim": integer,
  "rnnEncoderHiddenSize": integer,
  "rnnDecoderHiddenSize": integer,
  "rnnDecoderFullyConnectedSize": integer,
  "uiSequenceLength": integer,
  "maskLossFactor": integer,
  "deltaLossFactor": integer
}

For models that do not contain event data, the nnModelConfig structure is:

"nnModelConfig": {
  "modelType": "enum",
  "epochs": integer,
  "batchSize": integer,
  "earlyStopping": boolean,
  "recLossFactor": integer,
  "latentDim": integer,
  "maxCategoricalDim": integer,
  "encoderLayerSizes": [ integer ],
  "decoderLayerSizes": [ integer ]
}