Filtern: mit Fields

Daten lesen

Field-Filter sind Filterkriterien, die auf ein jeweiliges Dataset-Field angewendet werden können.

Dies kann bei lesenden API Endpunkten (..._get / ..._getList) und auch bei schreibenden Endpunkten (..._update, ..._delete) verwendet werden.

Parameter

Parameter Description Example
fields Felder, die zurückgegeben werden sollen  
filter Filter, um nach beliebigen Feldern und Werten das Ergebnis zu filtern  
sql (optional) Um LIMITs oder ORDERs (Sortierung) der Abfrage hinzuzufügen  
 
 

fields

Welche Felder zur Verfügung stehen, hängt vom jeweiligen Model ab. Details dazu gibt es hier in der Liste der Standard-Models.
Um die Performance zu erhöhen, sollten immer nur die Felder requested werden, die auch wirklich benötigt werden.
 

filter

Bis auf einige Ausnahmen, kann nach beliebigen Feldern gefiltert werden. Es stehen verschiedene Filter-Operatoren, je nach Feld-Typ, zur Verfügung.
Filter können für eine Vielzahl an Endpunkten verwendet werden.
Natürlich für die zentralen Dataset-API Endpunkte:  data_get, data_getList, data_update, data_delete .
 

Standard Filter Operatoren

Gleich (equal / like) - shorthand

Sicherlich sehr häufig verwendet: Das Filtern nach konkreten Werten in einem Feld.
 
The very basic filter. For number fields, such as integers or floats this translates to an: "is equal".
For text fields this translates to an: "caseinsensitive is equal"  (just like an e.g. MySQL: "LIKE").

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    "dataset": "<your dataset>",                 // Your dataset which you want to read and filter
    "fields": [ "<your fields...>", ... ],       // Your array of field names for values to be returned.

    "filter": { 
        "<your field>": "<filter value>"         // The actual filter! 
    }
}
 

Gleich (equal / OR )

You can pass one or more values of which it must match minimum one. This is basically an OR-combined equals-expression.

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    ...
    "filter": { 
        "<your field>": {
            "in": [ 
               "<value #1>",                   // <your field> must match one 
               "<value #2>",                   // these values
               ...
            ]
        }
    },
    ...
}
 
 

Ungleich (not equal)

You can pass one or more values it must not match. The single must-not-match values comparisons are AND-combined.

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    ...
    "filter": { 
        "<your field>": {
            "not_in": [ 
               "<not match value #1>",         // <your field> must not match this value
               "<not match value #2>",         // AND must not match this value
               ...
            ]
        }
    },
    ...
}
 

Größer als (greater than or equal)

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    ...
    "filter": { 
        "<your field>": {
            "range": { 
               "min": "<start value>"           // Compare <your field> with >= "<start value>"
            }
        }
    },
    ...
}
 

Kleiner als (Less than or equal)

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    ...
    "filter": { 
        "<your field>": {
            "range": { 
               "max": "<end value>"             // Compare <your field> with <= "<end value>"
            }
        }
    },
    ...
}
 

Bereich / Range

This is simply a combination of the previously mentioned min / max filters.

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    ...
    "filter": { 
        "<your field>": {
            "range": { 
               "min": "<start value>"           // Compare <your field> with >= "<start value>" 
               "max": "<end value>"             // Compare <your field> with <= "<end value>"
            }
        }
    },
    ...
}
 
 

Smart Filter (search in field)

Smart Filter erweitern die typischen Standard Filter Operatoren und ermöglichen eine Filter-Eingabe in reiner String-Form. Wie häufig von Benutzern in GUIs eingegeben.
 
Je nach Feldtyp stehen unterschiedliche Optionen zur Verfügung.
 
Allgemeines Parameter-Beispiel, am Beispiel für ein data_get:

Example Url: https://{your hublify url}/api/eos_10/data_get 

Parameters

{
    "dataset": "<your dataset>",                 // Your dataset which you want to read and filter
    "fields": [ "<your fields...>", ... ],       // Your array of field names for values to be returned.

    "filter": {
        "<your field>": {                        // The field you want to "smart filter"
            "search": "<filter value>"           // ! USE "search"-operator to activate "smart filter mode" !
        }
    }
}
 
 

Number

In Integer und Float-Feldern kann nach Zahlen und Bereichen gefiltert werden.
Es können mehrere Filter-Ausdrücke durch Semikolon getrennt angewendet werden.
 
Filter-Eingabe Beschreibung
10 Exakte Zahl
> 10 Größer als
>= 10 Größer gleich als
< 10 Kleiner als
<= 10 Kleiner gleich als
!= 10 ungleich
<> 10 ungleich
! 10 ungleich
0 - 100 Bereich, größer gleich 0 bis kleiner gleich 100
>=0 ; <=100 Bereich, größer gleich 0 bis kleiner gleich 100 (andere Schreibweise)
 

Example parameter

Filters for prices, in the range between 50 and 100:

{
    ...
    "filter": { 
        "price": {
            "search": ">=50;<=100"
    },
    ...
}
 

Text (Content Search)

Mit einem Text-Filter kann nach einem oder mehreren (Teil-) Suchbegriffen gesucht bzw. gefiltert werden.
 
Über dem einzelnen Suchbegriff vorangestellte Operatoren kann das Suchverhalten geändert werden. Im Normfall sind die Text-Filter unabhängig von Groß- und Kleinschreibung (case-insensitve)! Die folgend dargestellten Suchbegriffe können miteinander kombiniert werden.
 
Filter-Eingabe Beschreibung
abc Teilbegriffs-Suche. Sucht nach Teilbegriff abc. Liefert auch Treffer, wenn es im Wort oder am Wort-Ende vorkommt, wie bspw. bei " xxxabcxxx" und " yyyabc".
abc* Feldanfangs-Suche. Sucht nach Inhalten, bei denen der Feld-Inhalt mit abc anfängt.
*abc Feldende-Suche. Sucht nach Inhalten, bei denen der Feld-Inhalt mit abc aufhört.
abc xyz UND-Verknüpfung. Ein Leerzeichen zwischen Suchbegriffen entspricht automatisch einer UND-Verknüpfung der Suchbegriffe. Sucht hier bspw. nach Inhalten, bei denen abc UND xyz an beliebiger Position im Feld vorkommen. Die Reihenfolge dabei ist egal. Es können auch mehr als zwei Suchbegriffe verwendet werden.
"abc xyz" Genauer Ausdruck (in doppelten Anführungszeichen). Sucht nach Inhalten, bei denen genau die Zeichenkette " abc xyz" (inklusive Leerzeichen, aber ohne Anführungszeichen) vorkommt.
abc +xyz ODER-Verknüpfung. Ein vorangestelltes Plus-Zeichen entspricht einer ODER-Verknüpfung. Sucht hier bspw. nach Inhalten, bei denen abc ODER xyz vorkommt.
-abc Negativ-Suche. Sucht nach Inhalten bei denen abc nicht vorkommen darf.
!abc Negativ-Suche. Sucht nach Inhalten bei denen abc nicht vorkommen darf.
|| ODER-Verknüpfung / Klammern-Ersatz. Für komplexere Suchen, bei denen die Klammerung und anschließende ODER-Verknüfung von Suchbegriffen notwendig ist, kann dieser Operator, die doppelten-Pipe-Zeichen verwendet werden. Beispiel: " abc -def || xyz 123 || klm"
abc -xyz Kombinationsbeispiel. Sucht nach Inhalten, bei denen abc vorkommt aber nicht gleichzeitig xyz.
 

Example parameter

Filters for lastnames that contain "skywalker" or "kenobi":

{
    ...
    "filter": { 
        "lastname": {
            "search": "skywalker || kenobi"
    },
    ...
}
 

Text (Meta Search)

 
Filter-Eingabe Beschreibung
$NULL Sucht nach nicht gefüllten Inhalten.
!$NULL Sucht nach gefüllten Inhalten.
$EMPTY Sucht nach nicht gefüllten oder nur mit einem Leerstring gefüllten Inhalten.
!$EMPTY Sucht nach mit mehr als nur einem Leerstring gefüllten Inhalten.
$LENGTH > 10 mehr als 10 Zeichen
Sucht nach Inhalten, die eine gegebene Zeichenzahl überschreiten. Alternativ zu > können auch die anderen bei Filterung in Nummern-Spalten beschriebenen Operatoren verwendet werden
$LENGTH 10-100 zwischen 10-100 Zeichen
$WORDS > 10 mehr als 10 Wörter
Sucht nach Inhalten, die eine vorgegebene Wortzahl überschreiten. Als Wort gilt dabei jede durch ein Leerzeichen getrennte Zeichenkette. Die anderen Operatoren (siehe Filtern in Nummern-Spalten) können ebenso verwendet werden
$WORDS 10-100 zwischen 10-100 Wörtern
 
 

Date / DateTime

In Datum-Spalten kann komfortabel nach Zeiträumen gefiltert werden.
 
Filter-Eingabe Beschreibung
YYYY-MM-DD Absolutes Datum. Sucht nach Inhalten von diesem Tag zwischen 00:00 und 23:59:59 Uhr. Beispiel: " 2019-12-24".
DD.MM.YYYY Absolutes Datum (Deutsche Schreibweise). Sucht nach Inhalten von diesem Tag zwischen 00:00 und 23:59:59 Uhr. Beispiel: "24.12.2019" oder "1.1.2019".
MM.YYYY Absoluter Monat. Sucht nach Inhalten innerhalb des angegebenen Monats (Schaltjahre werden berücksichtigt), also vom 1. des Monats, 00:00 Uhr bis inklusive dem letzten Tag des Monats, 23:59:59 Uhr. Beispiel: "12.2019".
YYYY Absolutes Jahr. Sucht nach Inhalten innerhalb des angegebenen Jahres, also vom 1. Januar, 00:00 Uhr bis inklusive 31. Dezember, 23:59:59 Uhr. Beispiel: "2019".
englische Textform Relativer Zeitraum. Sucht nach Inhalten innerhalb des in englischer Textform angegebenen Zeitraums ausgehend vom aktuellen Datum. Beispiel: "last year", "this month".
- englische Textform Relatives Datum. Ausgehend vom aktuellen Datum wird um die angegebene Zeit zurückgerechnet. Sofern die relative Angabe keine Uhrzeit beinhaltet (" - 1hour"), wird der errechnete Tag komplett verwendet. Beispiel: " - 2 months", " -4 weeks".
> YYYY-MM-DD [hh:mm:ss] Zeitraum "nach" (auch deutsche Datumsschreibweise und relative Angaben). Sucht nach Inhalten ab dem Folgetag, 00:00 Uhr, des angegebenen Datums. Optional kann eine Uhrzeit angegeben werden, dann wird aber der Folge-Sekunde gesucht. Nicht angegebene Sekunden oder Minuten werden mit " 00" angenommen. Bei relativen Angaben wird ab dem Ende des darin beschriebenen Zeitraums gesucht. Beispiel: "> 2019-12-24", "> 2019-12-24 18:00", " > -4 weeks", " > last hour".
>= YYYY-MM-DD [hh:mm:ss] Zeitraum "nach, inklusive" (auch deutsche Datumsschreibweise und relative Angaben). Prinzipiell wie bei " >", nur eben inklusive des Angegebenen Zeitpunktes. Bei relativen Angaben wird ab dem Anfang des darin beschriebenen Zeitraums gesucht.
< YYYY-MM-DD [hh:mm:ss] Zeitraum "vor" (auch deutsche Datumsschreibweise und relative Angaben) Sucht nach Inhalten bis zu dem angegebenen Datum, 00:00 Uhr. Optional kann eine Uhrzeit angegeben werden, dann wird bis zu dieser Sekunde gesucht. Nicht angegebene Sekunden oder Minuten werden mit " 00" angenommen. Bei relativen Angaben wird vor dem Start des darin beschriebenen Zeitraums gesucht. Beispiel: "< 2019-12-24", "< 2019-12-24 18:00", " < last week".
<= YYYY-MM-DD [hh:mm:ss] Zeitraum "vor, inklusive". Prinzipiell, wie bei " <", nur eben inklusive des Angegebenen Zeitpunktes. Bei relativen Angaben wird bis zum Ende des darin beschriebenen Zeitraums gesucht.
YYYY-MM-DD [hh:mm:ss] - YYYY-MM-DD [hh:mm:ss] Freier Zeitraum (auch deutsche Datumsschreibweise und relative Angaben). Sucht nach Inhalten zwischen dem angegebenen Start- und Endzeitpunkt. Wird keine Start-Uhrzeit angegeben, so wird 00:00:00 Uhr angenommen. Wird keine End-Uhrzeit angegeben, so wird 23:59:59 Uhr angenommen. Beispiel: "1.1.2019 - 31.3.2019", "15.6.2019 12:00 - 16.6.2019 8:00", "-8weeks - -4weeks".
 

Example parameter

Filters for records where time_ordered (a DATETIME field) is in the range between 01.02.2020, 00:00:00 and 29.02.2020 23:59:59 (gap years are regarded):

{
    ...
    "filter": { 
        "time_ordered": {
            "search": "02.2020"
    },
    ...
}
 

Beispiele

data_get : Einzeldaten

Bei get-calls wird immer nur der erste gefundene Datensatz zurückgeben. get-calls werden typischerweise genutzt, um per primary-key einen Datensatz direkt zu lesen.

Url: https://{your hublify url}/api/eos_10/data_get

Parameters

{
    "dataset": "person",
    "fields": [ "personid", "firstname", "lastname" ],
    "filter": { 
        "personid": "K00000001"     // = a LIKE comparison (case insensitive)
    }
}

Response

Bei get-Calls wird der eigentliche Datensatz direkt unter [data] zurückgegeben.

{ 
    "data": {
        "personid": "K00000001",
        "firstname": "Luke",
        "lastname": "Skywalker"
    },
    "status": true
}
 

date_getList : Liste von Daten

Bei getList-calls werden die Daten als Array zurückgegeben.

Url: https://{your hublify url}/api/eos_10/data_getList

Parameters

{
    "dataset": "person",
    "fields": [ "personid", "firstname", "lastname" ],
    "filter": { 
        "lastname": "Skywalker"
    }
}

Response

Bei getList-Calls werden die Datensätze als numerisches Array unter [data] zurückgegeben.

{ 
    "data": [
        {
            "personid": "K00000001",
            "firstname": "Luke",
            "lastname": "Skywalker"
        },
        {
            "personid": "K00000003",
            "firstname": "Anakin",
            "lastname": "Skywalker"
        }
    ],
    "status": true
}