Query Elements

API Name

API Name: Elements – Query

---

Overview

This API searches and retrieves elements based on filtering, hierarchy scope, time range, and pagination.

MBSE Core uses this API for:

• Incremental synchronization

• Target lookup

• Criteria-based filtering

• Package-based browsing

• Bulk element retrieval

Connector responsibility:

• Apply hierarchy filters (parent + recursion).

• Apply time filters (afterTime, beforeTime) if supported.

• Apply structured filters and/or native query.

• Apply pagination.

• Respect expand options.

• Convert results into MbseElement objects.

• Return results in MbseElementListResponse.

---

API URI

POST: /mbse/api/1.0/elements/query
    ?projectIds={projectIds}
    &elementTypeIds={elementTypeIds}
    &branchId={branchId}
    &expand=PROPERTIES,TAGS,FILES,RELATIONS
    &properties={properties}
    &tags={tags}
    &pageNumber={pageNumber}
    &pageSize={pageSize}

---

URI Parameters

Name	Mandatory	Type	Description
projectIds	Yes	List	List of project IDs (comma-separated).
elementTypeIds	Yes	List	List of element type IDs.
branchId	No	String	Branch ID.
expand	No	List	Controls additional data fetch. Values: PROPERTIES, TAGS, FILES, RELATIONS.
properties	No	List	List of property IDs to include (if PROPERTIES expanded).
tags	No	List	List of tag IDs to include (if TAGS expanded).
pageNumber	Yes	Integer	0-based page index.
pageSize	Yes	Integer	Number of elements per page.

---

Request Body

{
  "parentElementIds": ["pkg_1"],
  "recursiveChildSearch": true,
  "afterTime": "2026-02-14T08:00:00Z",
  "beforeTime": "2026-02-15T08:00:00Z",
  "elementIds": ["el_1", "el_2"],
  "qualifiedNames": ["Model::System::Block"],
  "createdBy": "john.doe",
  "filters": {
    "status": "Approved"
  },
  "nativeQuery": "status = 'Approved'",
  "orderBy": [
    { "name": "updatedDate", "direction": "ASC" }
  ]
}

---

Request Body Parameters

Name	Required	Type	Description
parentElementIds	No	List	Restrict search to child hierarchy of given parents.
recursiveChildSearch	No	Boolean	If true, search recursively under parent hierarchy.
afterTime	No	ZonedDateTime	Return elements updated after this time.
beforeTime	No	ZonedDateTime	Return elements updated before this time.
elementIds	No	List	Restrict search to specific element IDs.
qualifiedNames	No	List	Search by qualified names.
createdBy	No	String	Filter by creator.
filters	No	Map<String,Object>	Structured filter criteria.
nativeQuery	No	String	Native query string (if supported).
orderBy	No	List	Sorting rules.

---

Behavior Rules

1. Parent Filtering

• If parentElementIds provided:

  • Return elements under these parents.

• If not provided:

  • Return root-level elements or full project search.

• If recursiveChildSearch = true:

  • Search entire hierarchy under parent.

• If false:

  • Search direct children only.

---

2. Time Filtering

• Apply afterTime and beforeTime if supported.

• If not supported:

  • Ignore at connector level.

  • MBSE Core may filter.

---

3. Element ID Filtering

• If elementIds provided:

  • Restrict results strictly to these IDs.

---

4. Filters & Native Query

• If filters provided:

  • Apply structured criteria.

• If nativeQuery provided:

  • Execute directly in end system.

• If both provided:

  • Combine logically if supported.

---

5. Pagination

• Pagination is mandatory.

• Implement using:

  • pageNumber

  • pageSize

• Must return only requested page.

---

6. Expand Behavior

Expand Value	Behavior
PROPERTIES	Include properties. Filter if properties provided.
TAGS	Include tags. Filter if tags provided.
FILES	Include attached files.
RELATIONS	Include relations.

If expand not provided:

• Return only base element metadata.

---

Response Payload

{
  "elements": [
    {
      "elementId": "block_101",
      "name": "System Block",
      "elementTypeId": "Block",
      "qualifiedName": "Model::System::Block",
      "projectId": "123",
      "createdBy": "john.doe",
      "updatedBy": "jane.smith",
      "createdDate": "2026-02-14T08:00:00Z",
      "updatedDate": "2026-02-14T09:00:00Z",
      "parentElementId": "pkg_1",
      "properties": {
        "status": "Approved"
      },
      "tags": {
        "criticality": "High"
      }
    }
  ]
}

---

Response Structure

MbseElementListResponse

Name	Required	Type
elements	Yes	List

---

Ordering

• Respect orderBy rules.

• Each rule:

  • name

  • direction (ASC, DESC)

• Default ordering: system-defined if not provided.

---

Error Handling

HTTP Status	Description
400	Invalid input parameters
404	Project or element type not found
500	Internal server error

---

Implementation Guidelines

• Avoid full-table scans where possible.

• Use native system query capabilities.

• Apply pagination at source system level.

• Avoid fetching properties/tags/files unless requested.

• Ensure ISO-8601 date format.

• Return deterministic results.

---

Design Rationale

This API enables:

• Scalable element retrieval

• Hierarchical search

• Time-based polling

• Target lookup

• Criteria-based filtering

It is the backbone of MBSE synchronization and search functionality.