# 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

```bash
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

```json
{
  "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

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opstech.gitbook.io/opstech-docs/mbse-connector-sdk-index/mbse-sdk-connector-apis/element-apis/element-query.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.