Paieška, filtravimas, rūšiavimas bei puslapiavimas

Paieška, filtravimas, rūšiavimas bei puslapiavimas

BSS API SEARCH metodai naudojami duomenų paieškai. Užklausoje galima nurodyti filtravimo kriterijus ir gauti tik reikalingus įrašus, rezultatus surūšiuoti norima tvarka bei pasirinkti, kurį rezultatų puslapį grąžinti. Taip integracijai nereikia kiekvieną kartą pasiimti visų BSS esančių duomenų ir jų papildomai atsirinkinėti savo sistemoje.

Svarbiausia taisyklė: naudokite konkretaus SEARCH metodo aprašyme pateiktus filtravimo laukus. Skirtingi metodai turi skirtingus galimus field, todėl viename metode naudojamas filtras nebūtinai bus galimas kitame.

Filtravimas

Filtravimas leidžia iš karto atsirinkti tik reikalingus įrašus. Pavyzdžiui, tabelių paieškoje galima ieškoti tik konkretaus mėnesio tabelių, o didžiosios knygos paieškoje – tik per pasirinktą laikotarpį sukurtų įrašų.

Kiekviena filtravimo sąlyga nurodo, pagal kurį lauką ieškoma, kokia sąlyga taikoma ir su kokia reikšme duomenys lyginami.

Laukas Ką reiškia?
field Laukas, pagal kurį filtruojami duomenys. Galimos reikšmės priklauso nuo konkretaus SEARCH metodo.
attributeNr Atributo identifikatorius, jei filtruojama pagal atributą. Jei kartu nurodomas ir field, pirmenybė teikiama field.
operator Nurodo, kaip pasirinkto lauko reikšmė turi būti lyginama. Jei operatorius nenurodytas, naudojamas equal.
value Reikšmė, su kuria lyginami duomenys. Priklausomai nuo pasirinkto lauko tai gali būti tekstas, skaičius, data, loginė arba kita metode numatyta reikšmė.

Praktiškai: jei norite gauti tik po tam tikros datos sukurtus įrašus, pasirenkamas atitinkamas datos field, palyginimo operator ir lauke value nurodoma data.

Filtravimo operatoriai

Operatorius nurodo, kaip pasirinkto lauko reikšmė turi būti lyginama su užklausoje perduota reikšme.

Operatorius Ką reiškia?
equal Lygu nurodytai reikšmei. Naudojamas pagal nutylėjimą.
notEqual Nelygu nurodytai reikšmei.
greater Daugiau už nurodytą reikšmę.
greaterOrEqual Daugiau arba lygu nurodytai reikšmei.
less Mažiau už nurodytą reikšmę.
lessOrEqual Mažiau arba lygu nurodytai reikšmei.
like Reikšmė turi atitikti nurodytą paieškos šabloną.
notLike Reikšmė neturi atitikti nurodyto paieškos šablono.
fullText Pilno teksto paieška.
isEmpty Atrenkami įrašai, kuriuose reikšmė neužpildyta.
isNotEmpty Atrenkami įrašai, kuriuose reikšmė užpildyta.

Svarbu: naudojant isEmpty arba isNotEmpty, lauke value lyginamos reikšmės nurodyti nereikia.

Keli filtrai vienoje paieškoje

Vienoje SEARCH užklausoje galima naudoti kelias filtravimo sąlygas. Jų tarpusavio ryšį nustato connector.

Reikšmė Ką reiškia?
and Įrašas turi atitikti visas nurodytas sąlygas. Tai numatytoji reikšmė.
or Pakanka, kad įrašas atitiktų bent vieną nurodytą sąlygą.

Sudėtingesnėms paieškoms galima naudoti innerFilters ir grupuoti filtravimo sąlygas. Pavyzdžiui, galima sudaryti paiešką pagal principą A ir (B arba C).

Rūšiavimas

Paieškos rezultatus galima grąžinti norima tvarka. Rūšiavimo sąlygoje nurodomas laukas, pagal kurį rūšiuojama, ir rūšiavimo kryptis.

Laukas Ką reiškia?
field Laukas, pagal kurį rūšiuojami rezultatai.
attributeNr Atributo identifikatorius, jei rūšiuojama pagal atributą.
direction asc – didėjančia tvarka, desc – mažėjančia tvarka. Jei reikšmė nenurodyta, naudojama asc.

Vienoje užklausoje galima nurodyti daugiau nei vieną rūšiavimo sąlygą. Tokiu atveju rezultatai pirmiausia rūšiuojami pagal pirmąją sąlygą, o toliau taikomos kitos nurodytos rūšiavimo sąlygos.

Puslapiavimas

Jei paieška randa daug įrašų, visi rezultatai vienu atsakymu negrąžinami. Duomenys pateikiami puslapiais, o užklausoje galima pasirinkti puslapio dydį ir nurodyti, kurį puslapį norite gauti.

Laukas Ką nurodyti?
pageSize Kiek įrašų grąžinti viename puslapyje. Galimos reikšmės – 50, 100 arba 200. Jei nenurodyta, naudojama 50.
pageNumber Kurį rezultatų puslapį grąžinti. Pirmojo puslapio numeris yra 0.

Pavyzdžiui, paieška rado 135 įrašus, o pageSize yra 50. Tokiu atveju rezultatai bus suskirstyti į tris puslapius:

pageNumber Kas bus grąžinta?
0 Pirmi 50 įrašų.
1 Kiti 50 įrašų.
2 Likę 35 įrašai.

Praktiškai: jei reikia visų rezultatų, neužtenka visada siųsti tik pageNumber: 0. Tą pačią paiešką kartokite keisdami pageNumber, kol bus gauti visi rezultatų puslapiai.

Kaip suprasti puslapiavimo informaciją atsakyme?

Paieškos atsakyme kartu su rastais duomenimis pateikiama informacija, pagal kurią galima nustatyti, kiek rezultatų rasta ir ar yra daugiau puslapių.

Laukas Ką reiškia?
pageSize Grąžinto puslapio dydis.
pageNumber Kurio puslapio duomenys grąžinti.
pageCount Kiek iš viso yra rezultatų puslapių.
totalCount Kiek iš viso rasta paieškos kriterijus atitinkančių įrašų.

Svarbu: jei pageCount yra didesnis nei 1 ir reikia visų duomenų, užklausą reikia kartoti su kitu pageNumber. Pavyzdžiui, jei pageCount yra 3, reikia pasiimti puslapius 0, 1 ir 2.

Bendra SEARCH užklausos struktūra

Paieškos užklausoje galima kartu perduoti filtravimo, rūšiavimo ir puslapiavimo informaciją:

{
  "filtering": {
    "filters": [
      {
        "field": "LAUKAS",
        "operator": "equal",
        "value": "REIKŠMĖ"
      }
    ]
  },
  "sorting": [
    {
      "field": "LAUKAS",
      "direction": "asc"
    }
  ],
  "pageSize": 50,
  "pageNumber": 0
}

Visi bendros SEARCH užklausos parametrai yra neprivalomi. Jei filtravimo ar rūšiavimo nereikia, jų perduoti nebūtina. Nenurodžius puslapiavimo parametrų, naudojamos numatytosios reikšmės.

Kokius laukus galima filtruoti?

Galimi filtravimo laukai priklauso nuo konkretaus SEARCH metodo. Viename metode gali būti galima filtruoti pagal datą, kitame – pagal numerį, kodą, būseną ar kitą tam objektui būdingą reikšmę. Prie konkrečių API metodų instrukcijų bus pateikiami detalesni tam metodui galimų filtrų paaiškinimai ir jų naudojimo pavyzdžiai.