Dynamic Query

Übersicht

Der Namespace /api/v1/dynamic/query stellt mehrere Endpunkte bereit, um flexible SQL-ähnliche Abfragen über JSON zu definieren. Die Engine übersetzt Request-Payloads in SQLAlchemy-Queries und unterstützt unter anderem:

• SELECT
• WHERE
• JOIN
• GROUP BY
• ORDER BY
• Subqueries in Filtern

Verfügbare Endpunkte:

• GET /api/v1/dynamic/query/tables
• GET /api/v1/dynamic/query/attributes
• POST /api/v1/dynamic/query
• POST /api/v1/dynamic/query/bulk
• POST /api/v1/dynamic/query/default-configuration

---

Modellnamen und Registry-Keys

Für query_model und target_model registriert die Engine sowohl:

• den kleingeschriebenen Klassennamen
• den kleingeschriebenen Tabellennamen

Dadurch funktionieren oft beide Varianten.

Beispiele:

• tenant oder tenants
• user oder users
• file oder files
• fileagent oder file_agents
• allowedextensions oder allowed_extensions
• agentphonenumber oder agent_phone_numbers

Die tatsächlich verfügbaren Keys kannst du über /api/v1/dynamic/query/tables abfragen.

Konsistente Keys verwenden

Wenn du Felder aus Joins referenzierst (z. B. tenant.domain oder fileagent.agent_id), verwende denselben Modell-Key konsistent in der gesamten Query.

---

Grundstruktur der Anfrage

Eine Dynamic-Query-Anfrage enthält typischerweise:

• query_model
• query_attributes
• optional query_filter
• optional joins
• optional group_by
• optional order_by
• optional page

curl https://api.livoi.de/api/v1/dynamic/query \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data '{
  "query_model": "user",
  "query_attributes": ["id", "email"],
  "page": { "page": 1, "size": 10 }
}'

query_attributes

Wenn query_attributes leer ist, selektiert der Service automatisch alle Spalten des Basismodells sowie aller registrierten Join-Modelle.

---

Schema & Metadaten

Verfügbare Tabellen auflisten

curl 'https://api.livoi.de/api/v1/dynamic/query/tables?include_attributes=true' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Beispielantwort:

{
  "tables": {
    "user": ["id","email","created_at"],
    "users": ["id","email","created_at"],
    "fileagent": ["id","file_id","agent_id"],
    "file_agents": ["id","file_id","agent_id"]
  }
}

Doppelte Einträge

Da sowohl Klassenname als auch Tabellenname registriert werden, können Keys wie user und users dieselben Attribute zurückgeben.

---

Attribute eines Modells abrufen

curl 'https://api.livoi.de/api/v1/dynamic/query/attributes?query_model=file' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Beispielantwort:

{
  "attributes": [
    "content_type",
    "created_at",
    "file_name",
    "id",
    "size",
    "tags",
    "title",
    "updated_at",
    "uri"
  ]
}

Gelieferte Attribute

Neben normalen Spalten können auch Hybrid-Properties oder Python-Properties erscheinen.
scope_id wird bewusst nicht zurückgegeben.

---

SQL-Operationen

SELECT

Einfache Spalten

{
  "query_model": "user",
  "joins": [
    { "target_model": "tenant", "on": "tenant_id=id" }
  ],
  "query_attributes": [
    "id",
    "email",
    "tenant.domain"
  ]
}

Projektionen

{
  "query_model": "agent",
  "query_attributes": [
    ["name","agent_name"],
    ["tenant.domain","tenant_domain"]
  ],
  "joins": [
    { "target_model": "tenant", "on": "tenant_id=id" }
  ]
}

Aggregationen

{
  "query_model": "history",
  "query_attributes": [
    "model_name",
    ["COUNT(id)","message_count"],
    ["SUM(usage_output_tokens)","total_tokens"]
  ],
  "group_by": ["model_name"]
}

---

WHERE-Filter

Format:

feld__operator

Operator erforderlich

Felder ohne Operator sind ungültig.

Statt:

permission_level

muss verwendet werden:

permission_level__eq

Unterstützte Operatoren:

Suffix	SQL
__eq	=
__ne	!=
__lt	<
__lte	<=
__gt	>
__gte	>=
__like	LIKE
__ilike	ILIKE
__in	IN
__not_in	NOT IN

Beispiel:

{
  "query_model": "user",
  "query_filter": {
    "permission_level__in": ["ADMIN","OWNER"],
    "last_login__gte": "2024-01-01T00:00:00Z"
  }
}

---

Subqueries

Beispiel:

{
  "id__in": {
    "subquery": {
      "query_model": "fileagent",
      "query_attributes": ["file_id"]
    }
  }
}

Subquery Verhalten

Die aktuelle Implementierung verwendet nur query_attributes[0].

Innerhalb von Subqueries funktionieren:

• query_filter
• group_by

Nicht angewendet werden aktuell:

• joins
• order_by
• page

---

JOIN

1. target_model

   Beispiele:

   tenant
   fileagent
   calendaragent

2. ON-Clause

   Format:

   left_field=right_field

   Beispiel:

   id=file_id

3. Join-Typ

   "isouter": true

   Erzeugt einen LEFT OUTER JOIN.

Beispiel:

{
  "query_model": "file",
  "joins": [
    {
      "target_model": "fileagent",
      "on": "id=file_id",
      "isouter": true
    }
  ],
  "query_attributes": [
    "id",
    "file_name",
    ["ARRAY_AGG(fileagent.agent_id)","agent_ids"]
  ],
  "group_by": ["id","file_name"]
}

---

ORDER BY

{
  "query_model": "user",
  "order_by": [
    "permission_level",
    "-last_login"
  ]
}

• field → aufsteigend
• -field → absteigend

---

GROUP BY

{
  "query_model": "chat",
  "query_attributes": [
    "user_id",
    ["COUNT(id)","chat_count"]
  ],
  "group_by": ["user_id"]
}

---

Bulk-Queries

curl https://api.livoi.de/api/v1/dynamic/query/bulk \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Beispiel-Body:

{
  "queries": [
    {
      "query_model": "user",
      "query_attributes": ["id","email"]
    },
    {
      "query_model": "history",
      "query_attributes": [
        "model_name",
        ["COUNT(id)","message_count"]
      ],
      "group_by": ["model_name"]
    }
  ]
}

---

Default-Konfiguration

POST /api/v1/dynamic/query/default-configuration

Filter:

• reference
• function

---

Fehlerbehandlung

403

{
  "status_code": "403",
  "status_message": "Forbidden"
}

404

{
  "status_code": "404",
  "status_message": "Not Found"
}

422

{
  "status_code": "422",
  "status_message": "Unprocessable Content"
}

500

{
  "status_code": "500",
  "status_message": "Internal Server Error"
}