executeQuery

R2026b

Execute query

Since R2026a

Syntax

elements = executeQuery(workspace,query)

Description

elements = executeQuery(workspace,query) returns one or more elements in elements that match the query expressed as a JSON string query that conforms to the SysML^® v2 API specification in the SysML v2 workspace specified by workspace. For more information on how to structure the query, see Systems Modeling API and Services.

Examples

Connect to Repository and Get Elements

This example shows how to connect to a SysML v2 repository, retrieve projects, and navigate elements using the System Composer™ SysML v2 API.

SysML v2 Project Content

This example assumes a SysML v2 project with specific content described by this SysML v2 text.

package test1 {
    part def myArch;
    part def subArch :> myArch;
    part def myTopArch {
      part A:subArch;
    }
}

If you have access to a SysML v2 editor, you can publish SysML v2 text into a repository.

Connect to a Local Repository

When published into a repository, the SysML v2 text is translated into SysML v2 elements you can access via the getElements function. First, connect to the server. If your server supports authentication via bearer token, then provide your token as the credentials argument systemcomposer.sysml.Repository.connect(serverUrl,credentials="my-token").

serverUrl = 'http://sysml-playground.home.com/api/v1/sysml/';
repo = systemcomposer.sysml.Repository.connect(serverUrl)

repo = 

  Repository with properties:

    BaseUri: 'http://sysml-playground.home.com/api/v1/sysml'

Get Projects

You can obtain information about all the projects in the repository by calling getProjects. Alternatively, if you know the project ID you want to use, you can retrieve the project directly by calling getProjectById.

allProjects = repo.getProjects();
projectToUse = repo.getProjectById('398687a6-cc37-4ef7-8e74-c30dd635181a')

projectToUse = 

  Project with properties:

    ResourceIdentifier: 'http://sysml-playground.home.com/api/v1/sysml/projects/398687a6-cc37-4ef7-8e74-c30dd635181a'
                    Id: '398687a6-cc37-4ef7-8e74-c30dd635181a'
           Description: 'Connect to Repository and Get Elements example'
                  Name: 'test1_docexample'

Create a Workspace

To look at the elements of a project, first create a workspace for a specified commit in the project by calling createWorkspace. If you call createWorkspace with no arguments, the created workspace is anchored to the head commit of the default branch and retrieves all elements. Alternatively, if you know the branch that you are working with, then you can provide the branch ID by calling createWorkspace(branchId="123456").

myFullWorkspace = projectToUse.createWorkspace()

myFullWorkspace = 
  Workspace with no properties.

Get All Elements

Calling getElements returns a list of all the elements in the snapshot for the anchored commit for the workspace and retrieves all elements that were not retrieved upon workspace creation. The output shows that this snapshot has 13 elements, which populates a local cache of the snapshot, organized as a graph based on the SysML v2 meta-model.

allElements = myFullWorkspace.getElements()

allElements = 

  1x13 Collection array with no properties.

Filter Elements by Type

You can now write code to inspect the elements of the workspace. For example, you can find all the elements that are of type Package. In this example, only one element, test1, has this type.

theOnlyPackage = allElements.Package;
theOnlyPackage.declaredName

ans = 

    "test1"

Navigate Element Relationships

From any element, you can navigate to related elements using the SysML v2 properties of that element. For example, you can look at one of the members of the package.

allOwnedMembers = theOnlyPackage.ownedMember
aMember = allOwnedMembers(3);
aMember.get("declaredName")

ans = 

    "myTopArch"

Explore Parts and Types

This member is a part definition that contains a single part. You can find that part and its type. The owner of this type is the original package.

thePart = aMember.ownedFeature(1);
thePartdeclaredName

ans = 

    "A"

thePartsType = thePart.type(1);
thePartsType.declaredName

ans = 

    "subArch"

backToTheStart = isequal(thePartsType.owner,theOnlyPackage)

backToTheStart =

  logical

   1

Display Element Properties

You can display the full properties of a SysML v2 element. Elements are represented using typed MATLAB^® classes such as sysml.PartUsage, sysml.PartDefinition, sysml.Package that reflect the SysML v2 meta-model.

thePart

thePart = 

  PartUsage with properties:

                        meta: "PartUsage"
                declaredName: "A"
                        name: "A"
                   elementId: "af0be269-cbd9-44f1-aea5-80f854e426a9"
                        type: [1x1 sysml.Collection]
                       owner: [1x1 sysml.PartDefinition]
          owningRelationship: [1x1 sysml.FeatureMembership]
           ownedRelationship: [1x1 sysml.Collection]
                 ownedTyping: [1x1 sysml.Collection]
                  isAbstract: 0
                 isComposite: 0
                   isDerived: 0
                     isEnd: 0
                 isOrdered: 0
                  isUnique: 0
                isVariable: 0
                ...

thePartsType

thePartsType = 

  PartDefinition with properties:

                        meta: "PartDefinition"
                declaredName: "subArch"
                        name: "subArch"
                   elementId: "391529c6-4b7f-4674-a8b7-30fab368aca6"
      ownedSubclassification: [1x1 sysml.Collection]
                       owner: [1x1 sysml.Package]
          owningRelationship: [1x1 sysml.OwningMembership]
           ownedRelationship: [1x1 sysml.Collection]
                  isAbstract: 0
                isSufficient: 0
                ...

Get Element Relationships

To learn more about how the elements are connected, get the element relationships around the PartUsage element.

elemRels = getElementRelationships(myFullWorkspace,thePart)

elemRels = 

  1x2 Collection array with no properties

Execute a Query

Confirm that the element thePart is the only element of type PartUsage.

queryString = '{"@type":"Query","name":"string","where":{"@type":"PrimitiveConstraint","operator":"=","property":"@type","value":["PartUsage"]}}';
flag = isequal(getElement(myFullWorkspace,"d94aa221-0952-4e8e-8a66-51488d990275"),...
executeQuery(work,queryString))

flag =

  logical

   1

Get Root Elements

Writing code is the most flexible approach to finding elements, but you can also get element relationships by looking at the root elements of a project. Root elements have no owner. In this case, the project has only one root element, which has a single member, the package test1.

root = myFullWorkspace.getRootElements()

root = 

  Namespace with properties:

                        meta: "Namespace"
                declaredName: []
                   elementId: "abaab9b1-b3fb-4e4e-a8a3-da60d4f29fd3"
           ownedRelationship: [1x1 sysml.Collection]
                 ownedMember: [1x1 sysml.Collection]
                       owner: [0x0]
                ...

rootMember = root.ownedMember;
rootMember(1).declaredName

ans = 

    "test1"

Find Elements by Type and Name

You can also find elements with a given meta type and name.

theTopArch = myFullWorkspace.getElementsByTypeAndName('PartDefinition','myTopArch');
theTopArch.declaredName

ans = 

    "myTopArch"

Explore Membership and Ownership Hierarchies

Once the elements for a given commit are in the cache, you can explore the element graph for the project in MATLAB. You can obtain some collections of elements via a single function call. For example, you can get all the members of a namespace by using getMembershipHierarchy. The first element in the returned vector is the source element. You can also retrieve the ownership hierarchy of an element by calling getOwnershipHierarchy. The first element of the vector is the source element.

myMembers = myFullWorkspace.getMembershipHierarchy(theOnlyPackage)

myMembers = 

  1x5 Collection array with no properties.

myOwners = myFullWorkspace.getOwnershipHierarchy(thePart)

myOwners = 

  1x4 Collection array with no properties.

Get Descendants

You can also easily classify elements in SysML v2. You can find the descendants of a definition by using the getDescendants method. In this case, subArch is the only descendant.

myArch = myFullWorkspace.getElementsByTypeAndName('PartDefinition','myArch');
mySubDefinitions = myFullWorkspace.getDescendants(myArch)

mySubDefinitions = 

  1x2 Collection array with no properties.

mySubDefinitions(end).declaredName

ans = 

    "subArch"

Get Ancestors

You can find the ancestors of a definition by calling getAncestors. In this case, myArch is the only ancestor.

subArch = myFullWorkspace.getElementsByTypeAndName('PartDefinition','subArch');
mySuperDefinitions = myFullWorkspace.getAncestors(subArch)
mySuperDefinitions(end).get("declaredName")

mySuperDefinitions = 

  1x2 Collection array with no properties.

mySuperDefinitions(end).declaredName

ans = 

    "myArch"

Get Usages of a Definition

You can also find all the usages of a given definition by using the getUsages method. In this project, only one definition has any usages, subArch, which has a PartUsage A.

theOnlyUsage = myFullWorkspace.getUsages(subArch);
theOnlyUsage(1).declaredName

ans = 

    "A"

Input Arguments

workspace — Workspace

workspace object

Workspace, specified as a systemcomposer.sysml.Workspace object.

query — Query

string

Query, specified as a JSON string that conforms to the SysML v2 API specification.

Example: '{"@type":"Query","name":"string","where":{"@type":"PrimitiveConstraint","operator":"=","property":"@type","value":["PartUsage"]}}'

Data Types: string

Output Arguments

elements — Elements

array of element objects

Elements, returned as an array of systemcomposer.sysml.Element objects.

More About

Definitions

Term	Definition	Application	More Information
Repository	A repository is a storage location for SysML v2 projects.	Connect to a remote repository via its URL. Then, retrieve the details of all projects in the repository.	systemcomposer.sysml.Repository
Project	A project is a container for SysML v2 data elements. A project contains a set of commits, which are time-stamped snapshots of the project. Projects also contain a set of branches that describe parallel development paths in the project.	Use projects to store data for a SysML v2 modeling activity.	systemcomposer.sysml.Project
Workspace	A workspace holds a local cache of the snapshot for a given project commit.	Use a workspace to access all SysML v2 elements in a snapshot at a given point in the evolution of a project.	systemcomposer.sysml.Workspace
Element	An element is a fundamental unit of modeling. Elements are the building blocks of SysML v2 models and include parts, blocks, requirements, activities, interfaces, and relationships. Each element has a unique identity within the repository and can be referenced and reused across projects.	An element in a workspace corresponds to a SysML v2 element or elements. You can use an element object to access data and relationships specific to a SysML v2 element.	sysml.Element

Version History

Introduced in R2026a