Retrieve

This chapter describes common query patterns for retrieving Construction Kit metadata. The Construction Kit API is read-only - you query the model structure but cannot modify it through GraphQL.

Query Structure

All Construction Kit queries use the constructionKit root field:

query {
  constructionKit {
    models { ... }
    types { ... }
    attributes { ... }
    enums { ... }
    records { ... }
    associationRoles { ... }
  }
}

Common Query Parameters

All Construction Kit queries support these parameters:

Pagination

Use first and after for cursor-based pagination:

query {
  constructionKit {
    types(first: 10, after: "YXJyYXljb25uZWN0aW9uOjk=") {
      totalCount
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
        startCursor
      }
      items {
        ckTypeId {
          fullName
        }
      }
    }
  }
}

Filter by ID

Use ckId to retrieve a specific item:

query {
  constructionKit {
    types(ckId: "Industry.Energy-1.0.0/EnergyMeter-1") {
      items {
        ckTypeId {
          fullName
          semanticVersionedFullName
        }
        description
        isAbstract
        isFinal
      }
    }
  }
}

Filter by Model

Use ckModelIds to filter by one or more models:

query {
  constructionKit {
    types(ckModelIds: ["Industry.Energy-1", "Basic-1"]) {
      totalCount
      items {
        ckTypeId {
          fullName
        }
      }
    }
  }
}

Field Filters

Use fieldFilter for attribute-based filtering:

query {
  constructionKit {
    models(
      fieldFilter: [
        { attributePath: "modelState", operator: EQUALS, comparisonValue: "AVAILABLE" }
      ]
    ) {
      items {
        id {
          fullName
        }
        modelState
      }
    }
  }
}

Search Filter

Use searchFilter for text search:

query {
  constructionKit {
    types(
      searchFilter: {
        searchTerm: "Energy"
        type: ATTRIBUTE_FILTER
        attributePaths: ["ckTypeId"]
      }
    ) {
      items {
        ckTypeId {
          fullName
        }
      }
    }
  }
}

Sort Order

Use sortOrder to define the result ordering:

query {
  constructionKit {
    types(
      sortOrder: [
        { attributePath: "ckTypeId", sortOrder: ASCENDING }
      ]
    ) {
      items {
        ckTypeId {
          fullName
        }
      }
    }
  }
}

Response Structure

All queries return a connection type with:

Field	Description
totalCount	Total number of matching items
pageInfo	Pagination cursors and flags
items	Array of result items

PageInfo

Field	Type	Description
endCursor	String	Cursor of the last item in the result
hasNextPage	Boolean	Whether more items exist after this page
hasPreviousPage	Boolean	Whether items exist before this page
startCursor	String	Cursor of the first item in the result

Component Queries

For detailed documentation on querying specific components:

Component	Documentation
Models	Models
Types	Types
Attributes	Attributes
Enums	Enums
Records	Records
Association Roles	Association Roles