Kubling Documentation

Script Document Data Source (`SCRIPT_DOCUMENT_JS`)

A Data Source that handles JSON and YAML documents and delegates the final processing steps to JavaScript.

As explained here the adapter exchanges JSON documents with your JavaScript, via bound objects.
Therefore, your scripts do not have to deal with the document build, since that happens at adapter level, so your scripts have only the logic to interact with other systems, which in most cases means calling its API.

When the engine receives, for example, and UPDATE query, the documents that match the criteria are returned by calling your resultSetScript, then, based on the type of table being updated, the engine updates the document/s and calls the script defined as updateScript.

💡

It is important to note that the resultSetScript must do its best effort to return documents that match the criteria, or WHERE clause, however when the system does not have specific filter mechanisms or it is complex to implement, your script can return documents not matching the criteria, since the result set is further inspected by the engine before returning the rows.

Configuration

Script Document Data Source configuration

type: "object"
id: "schema:kubling:dbvirt:model:vdb:sources:script:ScriptingSourceConfig"
properties:
  contextVariables:
    type: "object"
    description: "Additional variables to add to the Script context."
    additionalProperties:
      type: "object"
      id: "schema:kubling:InnerObject"
  contextOptions:
    type: "object"
    description: "Additional options to add to the Script context."
    additionalProperties:
      type: "string"
  module:
    type: "object"
    id: "schema:kubling:dbvirt:translation:scripting:base:model:Module"
    properties:
      name:
        type: "string"
      zipFilePath:
        type: "string"
        description: "URI of the module bundle."
  cache:
    type: "object"
    id: "schema:kubling:dbvirt:translation:model:CacheDataSourceConfig"
    properties:
      enabled:
        type: "boolean"
        description: "Specifies whether the cache is enabled for this Data Source.\
          \ Default is false."
      ttlSeconds:
        type: "integer"
        description: "The time-to-live (TTL) for cache entries, in seconds. Default\
          \ is 43,200 seconds (12 hours)."
  supportsPreCommit:
    type: "boolean"
  softTransactions:
    type: "object"
    id: "schema:kubling:dbvirt:model:vdb:sources:SoftTransactionsMvccSupportConfig"
    properties:
      enabled:
        type: "boolean"
        description: "Enables soft-transaction processing. When enabled, write operations\
          \ are captured and applied at transaction boundaries (prepare/commit), without\
          \ requiring the underlying system to provide transactional guarantees. Defaults\
          \ to false."
      strategy:
        type: "string"
        description: "Defines how soft transactions should be handled for this data\
          \ source. DEFER_OPERATION: write operations are staged and executed only\
          \ at commit time. IMMEDIATE_OPERATION: write operations are executed immediately\
          \ but also recorded in the transaction log for potential rollback. Exact\
          \ semantics vary by data source type. See source type-specific documentation.Defaults\
          \ to DEFER_OPERATION."
        enum:
        - "IMMEDIATE_OPERATION"
        - "DEFER_OPERATION"
      mvcc:
        type: "object"
        id: "schema:kubling:dbvirt:model:vdb:sources:MVCCSimConfig"
        description: "Enables the simulated MVCC engine for the data source. When\
          \ enabled, Kubling maintains per-transaction visibility using an internal\
          \ RocksDB-backed MVCC store. This allows DELETE/UPDATE/INSERT operations\
          \ within a transaction to override rows returned by your scripts. Defaults\
          \ to disabled."
        properties:
          enabled:
            type: "boolean"
            description: "Enables the MVCC simulation layer. When enabled, Kubling\
              \ maintains transaction-local visibility using versioned records. Rows\
              \ inserted, deleted or updated inside the transaction will override\
              \ values returned by the remote data source. Defaults to false."
          dbBasePath:
            type: "string"
            description: "Optional path to the RocksDB directory used to store MVCC\
              \ state locally. If not provided, Kubling will allocate an isolated\
              \ temporary directory."
  contributesToHealth:
    type: "boolean"
    description: "Indicates whether this data source contributes to the engine's overall\
      \ health status. When set to true, if this data source is not healthy, the engine\
      \ will be marked as unhealthy. Otherwise, the health status of this data source\
      \ is ignored in the overall assessment."

Sample configuration in VDB file:

- name: github
  dataSourceType: SCRIPT_DOCUMENT_JS
  configObject:
    module:
      zipFilePath: kbl://github/0.0.1
  translatorConfig: module:translator-config.yaml
  schema:
    type: PHYSICAL
    ddlFilePaths:
      - module:github.ddl

In the sample above, zipFilePath uses the kbl URL scheme that points to the Module repository configured in the Main application configuration, under moduleRepoBaseURI. By default, it points to https://repo.kubling.com.

translatorConfig and schema.ddlFilePaths point to files inside the module, that is why they use the special module: prefix. For more information please see Virtual Database information file.

Specific `TABLE` directives

Following directives work only in Document Data Sources (like this one)

Directive	Type	Options	Description
`synthetic_parent`	String	Any	Parent `TABLE`. Must include schema name.
`synthetic_path`	String	Any	Name of the parent `TABLE` field (array) used to ungroup the content
`synthetic_allow_bulk_insert`	Boolean	True/False	Indicates whether an INSERT operation tolerates multiple entries in the `synthetic_path` or must be strictly one.
`supports_idempotency`	Boolean	True/False	Indicates whether the upstream API supports idempotence. When `false` the QP verifies whether the operation changed the original record/document before applying. If omitted, the default value is `true`

Specific `COLUMN` directives

Directive	Type	Options	Description
`synthetic_type`	String	`parent`, `parent_array_key`	Type of the synthetic field. `parent` indicates that exists in and is connected to the parent entity. `parent_array_key` indicates that the field is used to locate specific elements within `synthetic_path`
`synthetic_parent_field`	String	Any	Indicates that the related parent field name is not the same as defined in the synthetic entity field. Used mostly when field names overlap.
`parser_format`	String	parser_format 'option' Options: `asJsonPretty`, `asYaml`, `asKeyValueList`	Applies a new format to the value, without altering it.

Kubernetes Embedded

Script Document Data Source (SCRIPT_DOCUMENT_JS)

Configuration

Specific TABLE directives

Specific COLUMN directives

Script Document Data Source (`SCRIPT_DOCUMENT_JS`)

Specific `TABLE` directives

Specific `COLUMN` directives