Vejledning om Kom godt igang med Elasticsearch

Inden du går i gang, vil vi ikke undlade at gøre opmærksom på, at Elasticsearch produktet har en omfattende referencedokumentation. Du vil med fordel kunne læse denne, inden du evt. forsøger dig frem, idet du hermed får en bedre forståelse for, hvad der er muligt, hvilket igen kan være med til at inspirere dig til lave en bedre løsning, her forstået som en løsning, der arbejder hurtigt, og som udnytter Elasticsearch på en optimal måde. 

Hvis du laver en løsning der ikke er optimal, i forhold til vores drift af Elasticsearch, kan du komme ud for, at vi midlertidigt bliver nødt til at spærre for din adgang.

Du har kun fået adgang til at fremsøge data via RESTful API’et, så du kan koncentrere dig om at forstå Elasticsearch forespørgsler, dvs. de forskellige typer af forespørgsler og det tilhørende forespørgsels-sprog (Query DSL).

For tiden anvender vi Elasticsearch v.6.8.23. Som ekstern bruger har man som sagt kun adgang til at fremsøge data, hvilket via RESTful API’et gøres ved at sende enten en http GET eller en POST request til /indeksnavn/type1 /_search endepunktet på frontend serveren, der sørger for at sende requestet videre til Elasticsearch, vente på svaret og returnere det til brugeren.

Man kan lave simple forespørgsler via GET request parametre, men det anbefales, at man bruger Elasticsearch query DSL sproget, som sendes i body af request’et (både GET og POST er understøttet). 

Query DSL giver mange flere muligheder, ligesom man enkelt kan begrænse størrelsen af svaret man modtager. Der jo ikke nogen grund til at modtage alle registrerede data om en virksomhed (også historiske), hvis man kun har behov for virksomhedens aktuelle navn.

Eksemplet viser: søg efter en virksomhed med cvr nr. 12345678 og returner virksomhedens aktuelle navn.

Hvis der ikke findes et virksomhed type dokument, der opfylder søgebetingelserne, kommer der et svar som vist i eksemplet:

Det interessante er sektionen: "hits":{"total":0, …}, der viser hvor mange dokumenter, der opfylder søgekriteriet.

Hvis man selv vil afprøve nogen af de viste eksempler, kan det gøres med fx kommando-linje værktøjet curl eller browser-plugin som fx Postman. 

Værktøjet skal understøtte afsendelse af et http request med Authorization header, Content-Type header og en request body med forespørgslen.

Eksemplet viser hvordan svaret gennem python JSON fortolkeren via en pipe, så vi får et pænt formateret resultat.

Eksemplet viser at – som forventet - der er fundet et resultat ("total": 1) som der kun returnerer virksomhedens navn: "NINE A/S" - som vi bad om. 

Prøv evt. at gentage forespørgslen, men denne gang uden linjen: "_source":["Vrvirksomhed.virksomhedMetadata.nyesteNavn.navn"], så du kan se alle data, der er registreret om virksomheden.

Når vi ser på hvordan data anvendes, er der to typiske hovedscenarier:

1. Simpel validering og opslag
2. Søgning på baggrund af virksomhedsnavn.

Det ene er, hvor man typisk ønsker at lave simple valideringer af dataregistreringer i eget system, hvor man derfor f.eks. ønsker at validere et indtastet CVR-nummer og vise det tilhørende virksomhedsnavn. 

Det kan også være hjælp til at finde et CVR-nummer på basis af et indtastet virksomhedsnavn, eller en del af et indtastet virksomhedsnavn. 

For begge eksempler har man oftest kun behov for at validere i forhold til de aktuelle virksomhedsdata, og man vil derfor med fordel kunne søge i "Vrvirksomhed.virksomhedMetadata" sektionen i virksomhed typen i Elasticsearch CVR-permanent indekset (som i eksemplet).

Man kan også finde et CVR-nummer ud fra et virksomhedsnavn.

Søgningen vil returnere følgende svar (det var i hvert fald tilfældet, da dette blev skrevet):

Her skal man forestille sig at brugeren har indtastet ”parken sport”, hvilket i ”query” delen udtrykkes som begge ord skal findes (AND) i attributten ”Vrvirksomhed.virksomhedMetadata.nyesteNavn.navn”. 

Det er også muligt at anvende wild-card søgninger med query_string operatoren. Eksemplet viser også at det var tilstrækkeligt for brugeren at indtaste ”parken sport”, idet der kun blev fundet et resultat, der opfyldte søgekriteriet. 

En anden ting man skal bemærke er ”size” attributten i forespørgslen, der beskriver hvor mange dokumenter, man maksimalt vil have i resultatet (standardværdien er 10), og nej, man kan ikke få alle dokumenter tilbage i en søgning, ved at specificere et tilstrækkeligt stort tal.

Et andet scenarie er at man ønsker af forskellige grunde, at have fx et udsnit af alle virksomhedsdata liggende i lokal kopi. 

Der skal man lave en søgning, der giver en mulighed for at hente alle de ønskede data, og at man med mellemrum skal fremsøge ændringer, i hvert fald hvis man vil holde sin egen lokale kopi opdateret.

Til dette formål skal man anvende en scroll søgning, hvor Elasticsearch returnerer virksomhedsdata i passende klumper, svarende til ”size” attributten. Elasticsearch læser data transaktionelt, således at man vil kunne gemme starttidspunktet for scroll søgningen, som efterfølgende vil kunne anvendes som starttidspunkt, når man senere skal fremsøge ændringer, så man kan vedligeholde den lokale kopi.

Hvis ens lokale register fx indeholder CVR-nummer., aktuelt navn og adresse, kan man udføre en scroll søgning som i eksemplet:

Resultatet af denne første søgning er et scroll_id samt første klump af de ønskede data. Inden udløbet af scroll perioden (i eksemplet ovenfor 1m = 1 minut som er den anbefalede værdi), skal man have lavet det næste kald igen, med det senest modtagne scroll_id. Dvs. så længe man bliver ved med at kalde indenfor scroll perioden holder Elasticsearch læse transaktionen aktiv. 

Man bliver ved med at kalde indtil man ikke længere modtager nogen hits, dvs. indtil hits array er tomt (i hvert fald hvis man ønsker at modtage alle dokumenter, der opfylder søgekriterierne). Hvis man har udfordringer med at nå at behandle alle de modtagne dokumenter indenfor et minut, er vores anbefaling klart at man nedjusterer size, fremfor at øge længden af scroll perioden. Vi forbeholder os retten til at spærre adgangen til Elasticsearch løsningen, hvis man ikke følger retningslinjerne.

De efterfølgende søgninger, der skal udføres, har alle formen som i eksemplet:

Så længe ens scroll transaktion er aktiv vil kaldet returnerer det næste scroll_id og den næste klump data som i eksemplet:

Når man er færdig med sit scroll, skal man huske at slette det igen (clear scroll), så Elasticsearch hurtigst muligt kan frigive allokerede ressourcer. Dette gøres ved at sende en DELETE request med det sidst modtagne scroll_id.

Scroll eksempel forespørgslen, der blev vist før, henter alle virksomheder (der bruges en match_all query), så man får data om alle virksomheder også de historiske. 

Hvis man kun ønsker data om aktive virksomheder, kan man i stedet bruge queryen i eksemplet::

Eksemplet viser, at så længe en virksomhed har et livsforløb med en åben periode (gyldigTil mangler), er den at betragte som aktiv. 

Queryen i eksemplet er nødt til at anvende en nested query, da der findes virksomhedsformer med flere livsforløb fx enkeltmandsvirksomheder.

Hermed er der ikke sagt noget om virksomhedens status, om den er fx er normal eller under konkurs (se Vrvirksomhed.virksomhedMetadata.sammensatStatus der indeholder den aktuelle værdi).

Når man skal hente opdateringer og nyoprettelser til sin lokale kopi, skal man igen lave en scroll søgning, hvor man skal fremsøge de virksomheder, der har et Vrvirksomhed.sidstIndlaest tidspunkt, som er større end eller lig med det tidspunkt, man gemte fra sidst man opdaterede. 

Den kan fx se således ud:

Her skal man blot være opmærksom på, at selv om virksomheden er blevet indlæst igen, er det ikke sikkert, at virksomheden faktisk er opdateret, ej heller at en evt. opdatering vedrører det udsnit af data, man har i sin lokale kopi, så ovenstående fremsøger sikkert for meget data, men til gengæld er det et simpelt søgeudtryk, og man er sikker på ikke at gå glip af nogen opdateringer.

Det er naturligvis muligt kun at fremsøge fx ændrede navne og/eller adresser via nested queries. 

De viste eksempler har alle taget udgangspunkt i virksomhed typen, der også indeholder referencer til produktionsenheder, som man kan finde alle detaljer om ved at søge i produktionsenhed typen på VrproduktionsEnhed.pNummer. 

Tilsvarende indeholder virksomhed typen også informationer om deltagerne, men også her gælder det, at den fulde information om en deltager findes i deltager typen ved at søge på Vrdeltager.enhedsNummer.

Dette bilag beskriver hvilken URL der skal anvendes, samt de dertilhørende basale POST-requests når der søges i Erhvervsstyrelsens ”System-til-system adgang til Registreringstekster”.

Søgning på CVR-nummer

BODY:
{
"query": {
"bool": {
"must": [
{
"term": {
"cvrNummer": "VALUE"
}
}
]
}
}
}

Søgning på offentliggørelsesperiode

BODY:
{
"query": {
"bool": {
"must": [
{
"range": {
"offentliggoerelseTidsstempel": {
"gte": "2020-09-04T00:00:01.000Z",
"lte": "2020-09-05T00:00:01.000Z"
}
}
}
]
}
}
}

Søgning på registreringsstatus

BODY:
{
"query": {
"bool": {
"must": [
{
"query_string": {
"default_field": "virksomhedsregistreringstatusser.keyword",
"query": "ANDET"
}
}
]
}
}
}
VÆRDISÆT for "virksomhedsregistreringstatusser.keyword"
”ANDET”
”AENDRING_KAPITAL”
”AENDRING_ADRESSE”
”AENDRING_REVISION”
”AENDRING_PERSONKREDS”
”AENDRING_STATUS”
”OMDANNELSE”
”NYT_SELSKAB”
”RETTELSE”
"FUSION_SPALTNING_OFFENTLIGGOERELSE"
"FUSION_SPALTNING_GENNEMFOERELSE"
"UOVERENSSTEMMELSE_REELLE_EJERE"