Zum Hauptinhalt springen

Abrufen

API-Ansätze​

OctoMesh bietet zwei Möglichkeiten, Entitäten abzufragen:

AnsatzEndpunktAnwendungsfall
Typisiertruntime.[typeName]Stark typisiert, IDE-Autovervollständigung, Validierung zur Kompilierzeit
Generischruntime.runtimeEntitiesDynamische Typbehandlung, flexibler Attributzugriff

Typisierte Abfrage (einfache Abfrage)​

Der Bereich runtime erlaubt den Zugriff auf Entitäten des Runtime-Modells Beginnen wir mit einem einfachen Beispiel, das Kunden von Energiegemeinschaften anfragt und den Runtime-Identifier (rtId), den Construction-Kit-Typ-Identifier (ckTypeId) sowie die Kontaktdaten aller Kunden zurückgibt.

query {
runtime {
energyCommunityCustomer {
items {
rtId
ckTypeId
contact{
companyName
firstName
lastName
}
}
}
}
}

Das Ergebnis dieser Abfrage

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"items": [
{
"rtId": "693c4cd3464d7d9e1396cf0d",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
},
{
"rtId": "693c4d97464d7d9e1396cf10",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "Jane",
"lastName": "Smith"
}
}
]
}
}
}
}

Diese Abfrage hat einige Nachteile. Die Anzahl der zurückgegebenen Objekte hängt von der Anzahl der gespeicherten Objekte ab. Das nächste Beispiel verwendet Pagination, um die Anzahl der zurückgegebenen Objekte zu begrenzen.


Generische Abfrage​

Der generische Endpunkt runtimeEntities erlaubt es, Entitäten eines beliebigen Typs dynamisch abzufragen. Das ist nützlich, wenn der Typ zur Kompilierzeit nicht bekannt ist oder wenn dynamische Anwendungen erstellt werden.

Einfache generische Abfrage​

query {
runtime {
runtimeEntities(ckTypeId: "OctoSdkDemo/Customer", first: 10) {
items {
rtId
ckTypeId
rtWellKnownName
rtCreationDateTime
rtChangedDateTime
attributes(first: 20) {
items {
attributeName
value
}
}
}
}
}
}

Antwort:

{
"data": {
"runtime": {
"runtimeEntities": {
"items": [
{
"rtId": "693c5b93464d7d9e1396cf1c",
"ckTypeId": "OctoSdkDemo/Customer",
"rtWellKnownName": "customer-001",
"rtCreationDateTime": "2024-01-15T10:30:00Z",
"rtChangedDateTime": "2024-01-20T14:00:00Z",
"attributes": {
"items": [
{ "attributeName": "customerStatus", "value": 1 },
{ "attributeName": "dateOfBirth", "value": "1985-03-15T00:00:00Z" },
{ "attributeName": "contact", "value": { "firstName": "John", "lastName": "Doe" } }
]
}
}
]
}
}
}
}

Felder des Typs RtEntity​

Der generische Typ RtEntity stellt die folgenden Felder bereit:

FeldTypBeschreibung
rtIdOctoObjectId!Eindeutiger Runtime-Identifier
ckTypeIdRtCkId!Construction-Kit-Typ-Identifier
rtWellKnownNameStringOptionaler Well-known-Name (technischer Identifier)
rtDisplayNameString!Berechneter Anzeigename, siehe Felder für Anzeigename
rtDisplayDescriptionStringBerechnete Anzeigebeschreibung, siehe Felder für Anzeigename
rtCreationDateTimeDateTimeErstellungszeitstempel
rtChangedDateTimeDateTimeZeitstempel der letzten Änderung
rtVersionIntVersionsnummer der Entität
attributesConnectionGenerischer Attributzugriff mit Filterung
associationsRtEntityGenericAssociationGenerischer Zugriff auf Assoziationen

Attribute filtern​

Das Feld attributes unterstützt die Filterung nach Attributnamen:

query {
runtime {
runtimeEntities(ckTypeId: "OctoSdkDemo/Customer", first: 10) {
items {
rtId
# Only retrieve specific attributes
attributes(
first: 10
attributeNames: ["customerStatus", "contact", "dateOfBirth"]
) {
items {
attributeName
value
}
}
}
}
}
}

Enum-Werte in Namen auflösen​

Standardmäßig werden Enum-Werte als Ganzzahlen zurückgegeben. Verwenden Sie resolveEnumValuesToNames: true, um menschenlesbare Namen zu erhalten:

query {
runtime {
runtimeEntities(ckTypeId: "OctoSdkDemo/Customer", first: 10) {
items {
rtId
attributes(first: 10, resolveEnumValuesToNames: true) {
items {
attributeName
value
}
}
}
}
}
}

Ohne resolveEnumValuesToNames:

{ "attributeName": "customerStatus", "value": 1 }

Mit resolveEnumValuesToNames: true:

{ "attributeName": "customerStatus", "value": "ACTIVE" }

Generische Assoziationen​

Das generische Feld associations stellt zwei Connections bereit, um verwandte Entitäten abzufragen:

Targets-Connection​

Die targets-Connection ruft verwandte Entitäten ab (Assoziationsziele):

query {
runtime {
runtimeEntities(ckTypeId: "OctoSdkDemo/MeteringPoint", first: 10) {
items {
rtId
associations {
targets(
roleId: "parent"
direction: OUTBOUND
ckId: "OctoSdkDemo/Customer"
first: 10
) {
items {
rtId
ckTypeId
attributes(first: 5) {
items {
attributeName
value
}
}
}
}
}
}
}
}
}

Targets-Argumente:

ArgumentTypErforderlichBeschreibung
roleIdString!JaDie Rollen-ID der Assoziation
directionGraphDirection!JaINBOUND oder OUTBOUND
ckIdString!JaDie Construction-Kit-Typ-ID des Ziels
includeIndirectBooleanNeinIndirekte Assoziationen einbeziehen (Standard: false)
searchFilterSearchFilterNeinVolltextsuchfilter
fieldFilter[FieldFilter]NeinFeldbasierte Filter
sortOrder[Sort]NeinSortierreihenfolge für Ergebnisse
aggregationsResultAggregationNeinAggregationsoptionen

Definitions-Connection​

Die definitions-Connection ruft Assoziationsmetadaten ab (die Assoziationsdatensätze selbst):

query {
runtime {
runtimeEntities(ckTypeId: "OctoSdkDemo/MeteringPoint", first: 10) {
items {
rtId
associations {
definitions(
direction: OUTBOUND
roleId: "parent"
first: 10
) {
items {
roleId
rtTargetId
ckTargetId
}
}
}
}
}
}
}

Definitions-Argumente:

ArgumentTypErforderlichBeschreibung
directionGraphDirection!JaINBOUND oder OUTBOUND
roleIdStringNeinFiltern nach Assoziationsrollen-ID
relatedRtCkIdRtCkIdNeinFiltern nach Zieltyp-ID
relatedRtIdOctoObjectIdNeinFiltern nach Zielentitäts-ID

Abfrage nach rtId mit der generischen API​

query {
runtime {
runtimeEntities(rtIds: ["693c5b93464d7d9e1396cf1c", "693c5b93464d7d9e1396cf1d"]) {
items {
rtId
ckTypeId
attributes(first: 20) {
items {
attributeName
value
}
}
}
}
}
}

Pagination​

query {
runtime {
energyCommunityCustomer(first: 1) {
pageInfo {
endCursor
startCursor
}
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

Diese Abfrage verwendet ein Argument first, das das Ergebnis auf 1 begrenzt. Wir verwenden pageInfo, um den Start- und End-Cursor abzurufen, um die Pagination fortzusetzen.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"pageInfo": {
"endCursor": "YXJyYXljb25uZWN0aW9uOjA=",
"startCursor": "YXJyYXljb25uZWN0aW9uOjA="
},
"items": [
{
"rtId": "693c4cd3464d7d9e1396cf0d",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
}
]
}
}
}
}

Der End-Cursor kann für die nächste Pagination verwendet werden:

query {
runtime {
energyCommunityCustomer(first: 1, after:"YXJyYXljb25uZWN0aW9uOjA=") {
pageInfo {
endCursor
startCursor
}
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

Das Ergebnis ist die nächste Seite:

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"pageInfo": {
"endCursor": "YXJyYXljb25uZWN0aW9uOjE=",
"startCursor": "YXJyYXljb25uZWN0aW9uOjE="
},
"items": [
{
"rtId": "693c4d3e464d7d9e1396cf0e",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
}
]
}
}
}
}

Abfrageoptionen​

Der Parameter options erlaubt es Ihnen, das Abfrageverhalten zu steuern. Standardmäßig werden archivierte Entitäten aus den Abfrageergebnissen ausgeschlossen.

OptionTypStandardBeschreibung
includeArchivedEntitiesBooleanfalseEntitäten einbeziehen, die archiviert wurden (weich gelöscht)

Archivierte Entitäten einbeziehen​

Um archivierte Entitäten in die Abfrageergebnisse einzubeziehen:

query {
runtime {
energyCommunityCustomer(options: { includeArchivedEntities: true }) {
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

Das ist nützlich, wenn Sie zuvor gelöschte Daten anzeigen oder wiederherstellen müssen. Siehe Löschen für weitere Informationen zum Archivieren von Entitäten.

Felder für Anzeigename​

Jede Entität stellt die schreibgeschützten Systemfelder rtDisplayName und rtDisplayDescription bereit. Ihre Werte werden von der Engine bei jedem Speichern aus den displayNameRule / displayDescriptionRule berechnet, die am Construction-Kit-Typ der Entität deklariert sind — siehe Display Name Rules für die Regelsyntax und Vererbung.

query {
runtime {
energyCommunityCustomer {
items {
rtId
rtDisplayName
rtDisplayDescription
}
}
}
}

Verhalten:

  • Schreibgeschützt: Die Felder werden beim Speichern berechnet (Insert, Replace und partielle Updates) und fehlen in allen Mutation-Input-Typen — sie können nicht über die API oder den Import gesetzt werden.
  • Fallback: Wenn der Typ keine Regel hat oder alle referenzierten Attribute leer sind, ist der gespeicherte Wert null. rtDisplayName ist im GraphQL-Schema non-null und gibt dann den Fallback <ckTypeId>@<rtId> zurück; rtDisplayDescription bleibt nullable.
  • Filtern und Sortieren: Beide Felder sind als System-Attributpfade für Feldfilter und Sortierreihenfolgen verfügbar, z. B. fieldFilter: [{attributePath: "rtDisplayName", operator: LIKE, comparisonValue: "*pump*"}]. Filterung und Sortierung arbeiten auf dem gespeicherten Wert, nicht auf dem synthetisierten Fallback.

Filteroptionen​

Es stehen verschiedene Filtertypen zur Verfügung, um Daten basierend auf bestimmten Bedingungen anzufragen. Filter können in einer einzelnen Abfrage kombiniert werden.

FiltertypBeschreibungDokumentation
rtId / rtIdsFiltern nach Runtime-Identifier(n)Siehe unten
fieldFilterFiltern nach AttributbedingungenSiehe unten
searchFilterVolltextsuche über Attribute hinwegSearchFilter
geoNearFilterGeospatiale FilterungSiehe unten

RtId-Filter​

Der rtId-Filter erlaubt es, Daten basierend auf dem Runtime-Identifier anzufragen. Der Typ des Arguments rtId ist ein Runtime-Identifier, der Typ des Arguments rtIds ist ein Array von Runtime-Identifiern.

query {
runtime {
energyCommunityCustomer(rtId: "693c4d3e464d7d9e1396cf0e") {
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

Das Ergebnis ist der Energiezähler mit dem Runtime-Identifier „6628101bf163c7c8f8676a33".

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"items": [
{
"rtId": "693c4d3e464d7d9e1396cf0e",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
}
]
}
}
}
}

Feldfilter​

Feldfilter erlauben es, Daten basierend auf bestimmten Bedingungen verschiedener Felder anzufragen. Mehrere Feldfilter werden mit dem logischen Operator AND kombiniert.

Eine vollständige Liste der verfügbaren Filteroperatoren finden Sie unter Überblick.

query {
runtime {
energyCommunityCustomer(fieldFilter:[{attributePath:"contact.lastName", operator:EQUALS, comparisonValue:"Doe"}]) {
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

geoNear-Filter​

Der geoNear-Filter erlaubt es, Daten von nah nach fern zu einem geospatialen Punkt zu filtern. Der Typ des Arguments geoNearFilter ist ein komplexes Objekt zur Konfiguration des Filters.

EigenschaftBeschreibung
attributeNameDer Attributname, der einen geospatialen Punkt darstellt
minDistanceMinimale Distanz von point, um Daten zu filtern, in Metern
maxDistanceMaximale Distanz von point, um Daten zu filtern, in Metern
pointEin Punkt, der einen Punkt angibt.
query getFireReports($position:PositionInput!, $minDistance:Float, $maxDistance:Float) {
runtime {
fireGuardiansFireReport(
first: 200,
geoNearFilter: {
attributeName: "location"
minDistance: $minDistance
maxDistance: $maxDistance
point: { coordinates: $position }
}
) {
items {
rtId
rtCreationDateTime
name
description
location {
distance
point {
coordinates {
latitude
longitude
}
}
}
}
}
}
}

Geospatiale Datentypen enthalten ein Feld, das – wenn der geoNear-Filter verwendet wird – die Distanz in Metern von dem im Filter angegebenen Punkt beschreibt.

{
"data": {
"runtime": {
"fireGuardiansFireReport": {
"items": [
{
"rtId": "65d5c447b420da3fb12381b9",
"rtCreationDateTime": "2022-02-22T09:00:00Z",
"name": "FireReport1",
"description": "FireReport1",
"location": {
"distance": 4508,
"point": {
"coordinates": {
"latitude": 48.123456,
"longitude": 11.123456
}
}
}
}
]
}
}
}
}

Sortierreihenfolge​

Die Standard-Sortierreihenfolge basiert auf der rtId. Die Sortierreihenfolge kann über das Argument sortOrder geändert werden. Das Argument ist ein Array von Objekten, die den Attributpfad und die Sortierrichtung enthalten.

Verfügbare Werte für die Sortierreihenfolge finden Sie unter Überblick.

Beispiel, um die Energiezähler nach Name in aufsteigender Reihenfolge zu sortieren:

query {
runtime {
energyCommunityCustomer(sortOrder:[{attributePath:"contact.firstName", sortOrder: DESCENDING}]) {
items {
rtId
ckTypeId
contact {
companyName
firstName
lastName
}
}
}
}
}

Das Ergebnis wird nach dem Namen in aufsteigender Reihenfolge sortiert.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"items": [
{
"rtId": "693c4cd3464d7d9e1396cf0d",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
},
{
"rtId": "693c4d3e464d7d9e1396cf0e",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
},
{
"rtId": "693c4d97464d7d9e1396cf0f",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "John",
"lastName": "Doe"
}
},
{
"rtId": "693c4d97464d7d9e1396cf10",
"ckTypeId": "EnergyCommunity/Customer",
"contact": {
"companyName": null,
"firstName": "Jane",
"lastName": "Smith"
}
}
]
}
}
}
}

Aggregationen​

Es stehen zwei Arten von Aggregationen zur Verfügung: Aggregation basierend auf dem gesamten Ergebnissatz oder die Verwendung von gruppierungsbasierten Aggregationen.

Aggregationen über den Ergebnissatz​

Der Typ des Arguments aggregations ist ein komplexes Objekt, das es erlaubt, verschiedene Arten von Aggregationen basierend auf dem gesamten Ergebnissatz zu konfigurieren.

FeldBeschreibung
minValueAttributePathsListe von Attributpfaden, auf die der Minimalwert innerhalb der Gruppe angewendet wird
maxValueAttributePathsListe von Attributpfaden, auf die der Maximalwert innerhalb der Gruppe angewendet wird
countAttributePathsListe von Attributpfaden, deren Werte (nicht null) gezählt werden
avgAttributePathsListe von Attributpfaden, auf die der Durchschnittswert innerhalb der Gruppe angewendet wird
query {
runtime {
energyCommunityCustomer(
aggregations: {
maxValueAttributePaths: ["contact.address.zipcode"]
}
) {
totalCount

aggregation{
count
maxStatistics{
attributePath
value
}
}
}
}
}

Das Ergebnis enthält die maximale Postleitzahl aller Kunden.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"totalCount": 9,
"aggregation": {
"count": 9,
"maxStatistics": [
{
"attributePath": "contact.address.zipcode",
"value": 80331
}
]
}
}
}
}
}

Aggregationen über den Ergebnissatz mit Gruppierung​

Die Gruppierung erlaubt es, Daten basierend auf Feldern zu gruppieren. Der Typ des Arguments groupBy ist ein komplexes Objekt, das es erlaubt, nach mehreren Feldern und der Art der Aggregation zu gruppieren.

FeldBeschreibung
aggregations.groupBy.groupByAttributePathsListe von Attributpfaden, auf die die Gruppierung angewendet wird
minValueAttributePathsListe von Attributpfaden, auf die der Minimalwert innerhalb der Gruppe angewendet wird
maxValueAttributePathsListe von Attributpfaden, auf die der Maximalwert innerhalb der Gruppe angewendet wird
countAttributePathsListe von Attributpfaden, deren Werte (nicht null) gezählt werden
avgAttributePathsListe von Attributpfaden, auf die der Durchschnittswert innerhalb der Gruppe angewendet wird

Das nächste Beispiel gruppiert die Kunden nach Bundesland und ruft die maximale Postleitzahl innerhalb jedes Bundeslands ab.

query {
runtime {
energyCommunityCustomer(
aggregations: {
groupBy: {
groupByAttributePaths: ["state"]
maxValueAttributePaths: ["contact.address.zipcode"]
}
}
) {
totalCount

fieldAggregations{
count
keys
maxStatistics{
attributePath
value
}
}
}
}
}

Das Ergebnis wird nach dem Bundesland gruppiert und enthält die maximale Postleitzahl innerhalb jedes Bundeslands.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"totalCount": 9,
"fieldAggregations": [
{
"count": 7,
"keys": [
1
],
"maxStatistics": [
{
"attributePath": "contact.address.zipcode",
"value": 67890
}
]
},
{
"count": 2,
"keys": [
2
],
"maxStatistics": [
{
"attributePath": "contact.address.zipcode",
"value": 80331
}
]
}
]
}
}
}
}

Assoziationen​

Assoziationen ermöglichen das Navigieren von Beziehungen zwischen Entitäten. Für eine detaillierte Dokumentation siehe Assoziationen.

Der einfachste Weg, auf Assoziationen zuzugreifen, führt über typisierte Navigationseigenschaften:

query
{
runtime{
energyCommunityCustomer(rtId: "693c4cd3464d7d9e1396cf0d"){
items{
rtId
facilities{
energyCommunityOperatingFacility{
items{
rtId
name
}
}
}
}
}
}
}

Das Ergebnis enthält die zugehörigen Betriebsanlagen des Kunden.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"items": [
{
"rtId": "693c4cd3464d7d9e1396cf0d",
"facilities": {
"energyCommunityOperatingFacility": {
"items": [
{
"rtId": "693c5b93464d7d9e1396cf1c",
"name": "Demo"
}
]
}
}
}
]
}
}
}
}

Generische Assoziationsabfrage​

Für dynamische Filterung nach Rolle, Richtung oder Zieltyp:

query
{
runtime{
energyCommunityCustomer(rtId: "693c4cd3464d7d9e1396cf0d"){
items{
rtId
associations(
roleId: "EnergyCommunity/AssociatedCustomer"
direction: INBOUND
ckId: "EnergyCommunity/OperatingFacility"
includeIndirect: true
){
items{
rtId
ckTypeId
}
}
}
}
}
}

Das Ergebnis enthält die zugehörigen Betriebsanlagen des Kunden.

{
"data": {
"runtime": {
"energyCommunityCustomer": {
"items": [
{
"rtId": "693c4cd3464d7d9e1396cf0d",
"associations": {
"items": [
{
"rtId": "693c5b93464d7d9e1396cf1c",
"ckTypeId": "EnergyCommunity/OperatingFacility"
}
]
}
}
]
}
}
}
}

Siehe Assoziationen für weitere Beispiele, einschließlich Richtungsfilterung, indirekter Assoziationen und Assoziationsdefinitionen.