Attributes

Attributes are reusable property definitions that can be applied to types. Each attribute has a value type and optional constraints.

List Attributes

Retrieve all attributes:

query getCkAttributes($after: String, $first: Int, $ckModelIds: [String]) {
  constructionKit {
    attributes(after: $after, first: $first, ckModelIds: $ckModelIds) {
      totalCount
      items {
        ckAttributeId {
          fullName
          semanticVersionedFullName
        }
        attributeValueType
      }
    }
  }
}

Response

{
  "data": {
    "constructionKit": {
      "attributes": {
        "totalCount": 25,
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Basic-1.0.0/Name-1",
              "semanticVersionedFullName": "Basic/Name"
            },
            "attributeValueType": "STRING"
          },
          {
            "ckAttributeId": {
              "fullName": "Industry.Energy-1.0.0/Voltage-1",
              "semanticVersionedFullName": "Industry.Energy/Voltage"
            },
            "attributeValueType": "DOUBLE"
          }
        ]
      }
    }
  }
}

Filter by Model

Retrieve attributes from specific models:

query {
  constructionKit {
    attributes(ckModelIds: ["Industry.Energy-1"]) {
      totalCount
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
      }
    }
  }
}

Attribute Details

Retrieve detailed information about a specific attribute:

query getCkAttributeDetails($attributeId: String) {
  constructionKit {
    attributes(ckId: $attributeId) {
      items {
        ckAttributeId {
          fullName
          semanticVersionedFullName
        }
        description
        attributeValueType
        defaultValues
        ckEnum {
          ckEnumId {
            fullName
            semanticVersionedFullName
          }
          useFlags
          isExtensible
          values {
            key
            name
            description
            isExtension
          }
        }
        ckRecord {
          ckRecordId {
            fullName
            semanticVersionedFullName
          }
          isAbstract
          isFinal
        }
      }
    }
  }
}

Variables:

{
  "attributeId": "Industry.Energy-1.0.0/State-1"
}

Response for Enum Attribute

{
  "data": {
    "constructionKit": {
      "attributes": {
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Industry.Energy-1.0.0/State-1",
              "semanticVersionedFullName": "Industry.Energy/State"
            },
            "description": "The operational state of the energy meter",
            "attributeValueType": "ENUM",
            "defaultValues": null,
            "ckEnum": {
              "ckEnumId": {
                "fullName": "Industry.Energy-1.0.0/EnergyMeterState-1",
                "semanticVersionedFullName": "Industry.Energy/EnergyMeterState"
              },
              "useFlags": false,
              "isExtensible": false,
              "values": [
                { "key": 0, "name": "OFF", "description": "Meter is off", "isExtension": false },
                { "key": 1, "name": "ON", "description": "Meter is on", "isExtension": false },
                { "key": 2, "name": "STANDBY", "description": "Meter is in standby", "isExtension": false }
              ]
            },
            "ckRecord": null
          }
        ]
      }
    }
  }
}

Response for Record Attribute

{
  "data": {
    "constructionKit": {
      "attributes": {
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Basic-1.0.0/Contact-1",
              "semanticVersionedFullName": "Basic/Contact"
            },
            "description": "Contact information",
            "attributeValueType": "RECORD",
            "defaultValues": null,
            "ckEnum": null,
            "ckRecord": {
              "ckRecordId": {
                "fullName": "Basic-1.0.0/Contact-1",
                "semanticVersionedFullName": "Basic/Contact"
              },
              "isAbstract": false,
              "isFinal": false
            }
          }
        ]
      }
    }
  }
}

Search Attributes

Search for attributes by name:

query {
  constructionKit {
    attributes(
      searchFilter: {
        searchTerm: "voltage"
        type: ATTRIBUTE_FILTER
        attributePaths: ["ckAttributeId.fullName"]
      }
    ) {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
      }
    }
  }
}

Attribute Fields

CkAttribute

Field	Type	Description
`ckAttributeId`	`CkAttributeId`	The attribute identifier
`description`	`String`	Description of the attribute
`attributeValueType`	`String`	The data type (STRING, INT32, ENUM, RECORD, etc.)
`defaultValues`	`[SimpleScalar]`	Default values for the attribute
`ckEnum`	`CkEnum`	Enum definition (if `attributeValueType` is ENUM)
`ckRecord`	`CkRecord`	Record definition (if `attributeValueType` is RECORD)

Attribute Value Types

Value	Description	GraphQL Input	GraphQL Output
`STRING`	Text value	`String`	`String`
`STRING_ARRAY`	Array of text values	`[String]`	`[String]`
`INT32`	32-bit integer	`Int`	`Int`
`INT32_ARRAY`	Array of 32-bit integers	`[Int]`	`[Int]`
`INT64`	64-bit integer	`Long`	`Long`
`FLOAT`	Floating-point number	`Float`	`Float`
`DOUBLE`	Double-precision floating-point number	`Decimal`	`Decimal`
`BOOLEAN`	True/false value	`Boolean`	`Boolean`
`DATE_TIME`	Date and time value	`DateTime`	`DateTime`
`DATE_TIME_OFFSET`	Date/time with timezone offset	`DateTimeOffset`	`DateTimeOffset`
`TIME_SPAN`	Duration/time interval (in seconds)	`Decimal` (seconds)	`Decimal` (seconds)
`BINARY`	Inline binary data (byte array)	`[Int]` (0-255)	`[Int]` (0-255)
`BINARY_LINKED`	Reference to external binary file	via REST API	`LargeBinaryInfo`
`OBJECT_ID`	MongoDB ObjectId reference	`OctoObjectId`	`OctoObjectId`
`ENUM`	Enumeration value (see linked `ckEnum`)	Generated Enum	Generated Enum
`RECORD`	Single embedded record (see linked `ckRecord`)	Generated Input	Generated Type
`RECORD_ARRAY`	Array of embedded records	`[Generated Input]`	`[Generated Type]`
`GEOSPATIAL_POINT`	Geospatial point coordinates	`PointInput`	`RtGeospatialValue`

Special Scalar Types

TimeSpan Attributes

TimeSpan attributes store duration/time interval values. In GraphQL, TimeSpan values are represented as seconds (decimal number).

YAML Definition:

attributes:
  - id: DataTransmissionInterval
    valueType: TimeSpan
    description: "Interval between data transmissions"

Query Example:

query {
  constructionKit {
    attributes(ckId: "OctoSdkDemo-1.0.0/DataTransmissionInterval-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "TIME_SPAN"
        description
      }
    }
  }
}

Runtime Query:

TimeSpan values are returned as seconds:

query {
  runtime {
    octoSdkDemoMeteringPoints(first: 10) {
      items {
        rtId
        meteringPointNumber
        dataTransmissionInterval  # Returns seconds as decimal
      }
    }
  }
}

Response:

{
  "data": {
    "runtime": {
      "octoSdkDemoMeteringPoints": {
        "items": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c",
            "meteringPointNumber": "MP-001",
            "dataTransmissionInterval": 900.0
          }
        ]
      }
    }
  }
}

Common TimeSpan values:

Duration	Seconds
1 minute	60
5 minutes	300
15 minutes	900
1 hour	3600
1 day	86400
1 week	604800

Complex Attribute Types

Record Attributes

Record attributes embed structured data within an entity. The record structure is defined separately in the Construction Kit.

YAML Definition:

attributes:
  - id: MainSpecification
    valueType: Record
    valueCkRecordId: ${this}/Specification
    description: "Main specification of the product"

Query Example:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/MainSpecification-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
        ckRecord {
          ckRecordId {
            fullName
          }
          attributes {
            items {
              attributeName
              attributeValueType
            }
          }
        }
      }
    }
  }
}

RecordArray Attributes

RecordArray attributes store arrays of structured records, useful for lists of specifications, contacts, or other repeated data structures.

YAML Definition:

attributes:
  - id: TechnicalSpecifications
    valueType: RecordArray
    valueCkRecordId: ${this}/Specification
    description: "List of technical specifications"

Query Example:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/TechnicalSpecifications-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "RECORD_ARRAY"
        ckRecord {
          ckRecordId {
            fullName
          }
        }
      }
    }
  }
}

Binary Attributes

Binary attributes store small binary data directly within the entity as inline byte arrays. This is ideal for small files like profile pictures, icons, or cached data where external file storage would be overkill.

YAML Definition:

attributes:
  - id: ProfilePicture
    valueType: Binary
    description: "Profile picture stored inline"

Query Example:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/ProfilePicture-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "BINARY"
        description
      }
    }
  }
}

Runtime Query - Binary Output:

Binary data is returned as an array of byte values (integers 0-255):

query {
  runtime {
    octoSdkDemoCustomers(first: 10) {
      items {
        rtId
        contact {
          firstName
          lastName
        }
        profilePicture  # Returns [137, 80, 78, 71, ...]
      }
    }
  }
}

Response:

{
  "data": {
    "runtime": {
      "octoSdkDemoCustomers": {
        "items": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c",
            "contact": {
              "firstName": "John",
              "lastName": "Doe"
            },
            "profilePicture": [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13]
          }
        ]
      }
    }
  }
}

Binary vs BinaryLinked

Binary: Small data stored inline (< 16MB), immediate access, no separate download
BinaryLinked: Large files stored externally, requires REST API download

BinaryLinked Attributes

BinaryLinked attributes store references to external binary files (images, documents, PDFs, etc.). Files are uploaded via GraphQL Multipart Request and downloaded via the REST API. The entity stores only the reference metadata.

YAML Definition:

attributes:
  - id: ProductImage
    valueType: BinaryLinked
    description: "Product image file"

  - id: ProductDatasheet
    valueType: BinaryLinked
    description: "Product datasheet document"

Query Example:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/ProductImage-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "BINARY_LINKED"
        description
      }
    }
  }
}

Runtime Query - BinaryLinked Output:

When querying entities with BinaryLinked attributes, you receive metadata about the binary:

query {
  runtime {
    products(first: 10) {
      items {
        productImage {
          binaryId
          filename
          contentType
          size
          downloadUri
        }
      }
    }
  }
}

LargeBinaryInfo Fields:

Field	Type	Description
`binaryId`	`OctoObjectId`	Unique identifier of the binary
`filename`	`String`	Original filename
`contentType`	`String`	MIME type (e.g., `image/png`)
`size`	`Long`	File size in bytes
`downloadUri`	`String`	URI to download the binary content

tip

For creating and updating entities with complex attribute types, see:

List Attributes​

Response​

Filter by Model​

Attribute Details​

Response for Enum Attribute​

Response for Record Attribute​

Search Attributes​

Attribute Fields​

CkAttribute​

Attribute Value Types​

Special Scalar Types​

TimeSpan Attributes​

Complex Attribute Types​

Record Attributes​

RecordArray Attributes​

Binary Attributes​

BinaryLinked Attributes​

List Attributes

Response

Filter by Model

Attribute Details

Response for Enum Attribute

Response for Record Attribute

Search Attributes

Attribute Fields

CkAttribute

Attribute Value Types

Special Scalar Types

TimeSpan Attributes

Complex Attribute Types

Record Attributes

RecordArray Attributes

Binary Attributes

BinaryLinked Attributes