Writeback CRUD Operations

Content-Type (Required)

String

Specifies media type of request body.

application/x-www-form-urlencoded

sessionid

String

The session ID is the token received from the login API.

Note: Session ID is required for token-based authentication.

–

name-or-id (Required)

String

Name or ID of the Semantic Model on which the writeback operation will be performed.

Note: If the Semantic Model name is provided, then folderName must also be provided in request body.

–

by

String

Specifies whether the name-or-id parameter should be interpreted as a Semantic Model name or Semantic Model ID.

If by=name, provide the Semantic Model name in the name-or-id parameter.

If by=id, provide the Semantic Model ID in the name-or-id parameter.

The default value is name.

–

folderName

String

Folder name of the Semantic Model on which the writeback operation is to be performed. If the Semantic Model is present in the root directory, specify [Root].

Note: If folderName is not provided, the Semantic Model will be treated as a root-level entity by default.

–

operation (Required)

String

Specifies the writeback action to be performed.

UPDATE: Modifies the existing value with the provided changes.

DISCARD: Reverts and removes all uncommitted changes.

COMMIT: Persists the modified changes permanently.

positionsJson (Required)

String

An array of positions (data points) for bulk writeback operations. Each position contains members, filters, originalValue, prevValue and newValue required to perform the writeback. The combination of members and filters must uniquely identify the target data point for the writeback operation.

Note: An example JSON is provided under the Resources section below.

–

401

Authorization information is missing or invalid.

404

Connection, database, schema, or table not found.

412

Precondition failed. Required parameter missing.

500

Internal Server Error

Field

Type

Description

Possible values 

Example

type

String

Identifies the writeback change type for this individual position. Optional, defaults to UPDATE if omitted.

UPDATE or INSERT are the normal position types.

UPDATE

members

Array of JSON objects

Identifies the dimension members and measure that form the target data cell. The selected members must combine with filters, if provided, to identify exactly one data point. Required for meaningful UPDATE and INSERT operations. For INSERT, include at least one member whose fieldType is MEASURE.

One or more member objects.

[{"id":"DIM_328688","fieldType":"LEVEL","name":"2012"},{"id":"MEASURE_2010","fieldType":"MEASURE","name":"Sales Amount"}]

members[].id

String

Unique internal identifier of the selected member or measure. This allows Kyvos to locate the exact dimension level, attribute member, or measure. Required for every member.

Existing member or measure ID from the semantic model or query response.

DIM_328688

members[].fieldType

String

Specifies whether the selected item is a dimension level, an attribute, or a measure. Required for every member.

LEVEL, ATTRIBUTE, MEASURE.

LEVEL

members[].name

String

Human-readable member name. For a measure member, provide the measure name used by the semantic model. Required for every member.

Existing member caption or measure name.

2012

filters

Array of JSON objects

Adds extra conditions used to narrow the target data point when members alone do not uniquely identify it. Optional.

One or more filter objects.

[{"fieldName":"DIM_175!!!H_270!!!DIMENSION_LEVEL_648","operation":"EQUAL_TO","firstValue":"Actual"}]

filters[].fieldName

String

Internal qualified name of the semantic-model field on which the filter is applied. Required for each usable filter.

Existing qualified dimension, attribute, level, or measure field name.

DIM_175!!!H_270!!!DIMENSION_LEVEL_648

filters[].operation

String

Comparison rule used to evaluate the filter value. Required for each usable filter.

Common values include EQUAL_TO, NOT_EQUAL_TO, INLIST, NOT_IN_LIST, STARTSWITHIGNORECASE, GREATER_THAN, LESS_THAN, BETWEEN, and LIKE. Use an operation supported by the selected field type.

EQUAL_TO

filters[].firstValue

String

Primary value used by the selected filter operation. Required for filters that compare against one or more values, including EQUAL_TO and INLIST.

A value valid for the selected field. For multiple values, use the delimiter supported by the filter definition.

Actual

filters[].secondValue

String

Second comparison value used for range-based operations, such as BETWEEN. Optional; required only when the selected operation needs a second value.

A value valid for the selected field.

12/31/2026

filters[].firstDisplayValue

String

Friendly display text for firstValue. It helps preserve the label shown to users when the stored value and displayed value are different. Optional.

Text corresponding to firstValue.

Jan-26

filters[].secondDisplayValue

String

Friendly display text for secondValue. Optional; required only when secondValue is used and its displayed text differs from its stored value.

Text corresponding to secondValue.

Dec-26

filters[].id

String

Internal identifier of the filter field. Optional; use it when the field requires an ID in addition to fieldName.

Existing filter or field ID.

DIM_175

filters[].fieldType

String

Identifies the type of field being filtered. Optional but recommended when the filter is not unambiguous from fieldName.

Common values include LEVEL, ATTRIBUTE, DIMENSION, or MEASURE.

LEVEL

filters[].dataType

String

Defines the data type of the filter value so Kyvos can interpret it correctly.

For example CHAR, NUMBER, DATE.

CHAR

filters[].fieldDisplayName

String

User-friendly name of the filtered field. Optional.

Display name configured in the semantic model.

Scenario

filters[].relation

String

Defines how this filter is combined with other filters in the same position. Optional; defaults to AND when omitted.

AND, OR.

AND

filters[].valueDelimiter

String

Character or text used to separate multiple values in firstValue or secondValue. Optional; mainly used with list-based operations.

Delimiter supported by the filter definition.

,

filters[].startEnclosure

String

Opening character used to enclose a filter value when the query syntax requires it. Optional.

Usually an empty string, single quote, or opening bracket.

{

filters[].endEnclosure

String

Closing character used to enclose a filter value when the query syntax requires it. Optional.

Usually an empty string, single quote, or closing bracket.

}

filters[].isMemberValue

Boolean

Indicates whether the supplied value represents a member value rather than another field expression. Optional.

true, false.

TRUE

filters[].isAppliedOnDisplayField

Boolean

Indicates whether Kyvos applies the filter to the field’s displayed value instead of its internal value. Optional.

true, false.

FALSE

filters[].isUseField

Boolean

Indicates whether the filter uses another field as its comparison source. Optional.

true, false.

FALSE

filters[].useFieldType

String

Specifies how the alternate field is used when isUseField is true. Optional; relevant only when isUseField is true.

Value type supported by the filter configuration.

VALUE

filters[].isParameter

Boolean

Indicates whether the filter value is supplied from a semantic-model parameter. Optional.

true, false.

FALSE

filters[].firstParameterValue

String

Name or value of the parameter supplying firstValue. Optional; relevant only when isParameter is true.

Existing semantic-model parameter reference.

Selected Scenario

filters[].secondParameterValue

String

Name or value of the parameter supplying secondValue. Optional; relevant only for range filters that use a parameter for the second value.

Existing semantic-model parameter reference.

End Date

filters[].isFirstValueQualified

Boolean

Indicates whether firstValue is already supplied in fully qualified member format. Optional.

true, false.

FALSE

filters[].firstValueLevelIndex

String

Identifies the hierarchy level associated with firstValue. Optional; use when filtering a hierarchy member requires an explicit level.

Valid hierarchy-level index.

0

filters[].filterType

String

Categorizes the filter for Kyvos query processing. Optional.

Filter type supported by the semantic model and selected operation. e.g: QUICK

QUICK

filters[].valueType

String

Indicates how the filter value is obtained, such as a predefined value or another supported value source. Optional.

Value type supported by the filter configuration.

predefined

filters[].valueBy

String

Further specifies the source or method used to obtain the filter value. Optional.

Value-source setting supported by the filter configuration.

VALUE

filters[].searchContext

String

Search context used when resolving filter values. Optional.

Context value supported by the semantic model.

DEFAULT

filters[].sortOrder

String

Sort direction used when the filter result needs ordered values. Optional.

ASC, DESC.

ASC

filters[].isActive

Boolean

Indicates whether the filter is active. Optional.

true, false.

TRUE

filters[].isIncludedForContextSearch

Boolean

Indicates whether this filter participates in contextual member searching. Optional.

true, false.

TRUE

filters[].isSearchFilter

Boolean

Indicates whether this filter is used specifically as a search filter. Optional.

true, false.

FALSE

filters[].includeCurrent

Boolean

Indicates whether the current date or current member should be included for applicable dynamic filtering. Optional.

true, false.

FALSE

filters[].fieldEntityInfo

JSON object

Provides additional field metadata when the filter requires entity-level information. Optional.

Object structure depends on the selected field and semantic model.

{"id":"DIM_175","name":"Scenario"}

originalValue

String

Value that was originally stored in the target cell before any writeback changes. Required when type is UPDATE because Kyvos uses it to verify the intended cell state.

Value in the target measure’s storage format.

100

prevValue

String

Most recently known value of the target cell before this update. Required when type is UPDATE because Kyvos uses it to detect conflicting changes.

Value in the target measure’s storage format.

100

updatedValue

String

New value that Kyvos should write to the target cell. Required when type is UPDATE or INSERT.

Value valid for the selected measure’s data type and writeback rules.

125