Abrufen
API-Ansätze
OctoMesh bietet zwei Möglichkeiten, Entitäten abzufragen:
| Ansatz | Endpunkt | Anwendungsfall |
|---|---|---|
| Typisiert | runtime.[typeName] | Stark typisiert, IDE-Autovervollständigung, Validierung zur Kompilierzeit |
| Generisch | runtime.runtimeEntities | Dynamische 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:
| Feld | Typ | Beschreibung |
|---|---|---|
rtId | OctoObjectId! | Eindeutiger Runtime-Identifier |
ckTypeId | RtCkId! | Construction-Kit-Typ-Identifier |
rtWellKnownName | String | Optionaler Well-known-Name (technischer Identifier) |
rtDisplayName | String! | Berechneter Anzeigename, siehe Felder für Anzeigename |
rtDisplayDescription | String | Berechnete Anzeigebeschreibung, siehe Felder für Anzeigename |
rtCreationDateTime | DateTime | Erstellungszeitstempel |
rtChangedDateTime | DateTime | Zeitstempel der letzten Änderung |
rtVersion | Int | Versionsnummer der Entität |
attributes | Connection | Generischer Attributzugriff mit Filterung |
associations | RtEntityGenericAssociation | Generischer 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:
| Argument | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
roleId | String! | Ja | Die Rollen-ID der Assoziation |
direction | GraphDirection! | Ja | INBOUND oder OUTBOUND |
ckId | String! | Ja | Die Construction-Kit-Typ-ID des Ziels |
includeIndirect | Boolean | Nein | Indirekte Assoziationen einbeziehen (Standard: false) |
searchFilter | SearchFilter | Nein | Volltextsuchfilter |
fieldFilter | [FieldFilter] | Nein | Feldbasierte Filter |
sortOrder | [Sort] | Nein | Sortierreihenfolge für Ergebnisse |
aggregations | ResultAggregation | Nein | Aggregationsoptionen |
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:
| Argument | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
direction | GraphDirection! | Ja | INBOUND oder OUTBOUND |
roleId | String | Nein | Filtern nach Assoziationsrollen-ID |
relatedRtCkId | RtCkId | Nein | Filtern nach Zieltyp-ID |
relatedRtId | OctoObjectId | Nein | Filtern 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.
| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
includeArchivedEntities | Boolean | false | Entitä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.rtDisplayNameist im GraphQL-Schema non-null und gibt dann den Fallback<ckTypeId>@<rtId>zurück;rtDisplayDescriptionbleibt 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.
| Filtertyp | Beschreibung | Dokumentation |
|---|---|---|
rtId / rtIds | Filtern nach Runtime-Identifier(n) | Siehe unten |
fieldFilter | Filtern nach Attributbedingungen | Siehe unten |
searchFilter | Volltextsuche über Attribute hinweg | SearchFilter |
geoNearFilter | Geospatiale Filterung | Siehe 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.
| Eigenschaft | Beschreibung |
|---|---|
| attributeName | Der Attributname, der einen geospatialen Punkt darstellt |
| minDistance | Minimale Distanz von point, um Daten zu filtern, in Metern |
| maxDistance | Maximale Distanz von point, um Daten zu filtern, in Metern |
| point | Ein 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.
| Feld | Beschreibung |
|---|---|
| minValueAttributePaths | Liste von Attributpfaden, auf die der Minimalwert innerhalb der Gruppe angewendet wird |
| maxValueAttributePaths | Liste von Attributpfaden, auf die der Maximalwert innerhalb der Gruppe angewendet wird |
| countAttributePaths | Liste von Attributpfaden, deren Werte (nicht null) gezählt werden |
| avgAttributePaths | Liste 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.
| Feld | Beschreibung |
|---|---|
| aggregations.groupBy.groupByAttributePaths | Liste von Attributpfaden, auf die die Gruppierung angewendet wird |
| minValueAttributePaths | Liste von Attributpfaden, auf die der Minimalwert innerhalb der Gruppe angewendet wird |
| maxValueAttributePaths | Liste von Attributpfaden, auf die der Maximalwert innerhalb der Gruppe angewendet wird |
| countAttributePaths | Liste von Attributpfaden, deren Werte (nicht null) gezählt werden |
| avgAttributePaths | Liste 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.
Navigationseigenschaften
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.