streamalism.org

1. Introduktion

Enhver, der har arbejdet med Elasticsearch, ved, at bygningsforespørgsler ved hjælp af deres RESTful search API kan være kedelig og fejlbehæftet.

I denne vejledning ser vi på Jest, en HTTP Java-klient til Elasticsearch. Mens Elasticsearch leverer sin egen native Java-klient, Jest giver en mere flydende API og lettere grænseflader at arbejde med.

2. Maven-afhængighed

Den første ting, vi skal gøre, er at importere Jest-biblioteket til vores POM:

 io.searchbox jest 6.3.1 

Versionen til Jest følger den af ​​det vigtigste Elasticsearch-produkt. Dette hjælper med at sikre kompatibilitet mellem klient og server.

Ved at inkludere Jest-afhængighed vil det tilsvarende Elasticsearch-bibliotek blive inkluderet som en transitiv afhængighed.

3. Brug af Jest Client

I dette afsnit ser vi på at bruge Jest-klienten til at udføre almindelige opgaver med Elasticsearch.

For at bruge Jest-klienten opretter vi simpelthen en JestClient objekt ved hjælp af JestClientFactory. Disse objekter er dyre at skabe og er trådsikre, så vi opretter en singleton-forekomst, der kan deles i hele vores applikation:

offentlig JestClient jestClient () {JestClientFactory fabrik = ny JestClientFactory (); factory.setHttpClientConfig (ny HttpClientConfig.Builder ("// localhost: 9200") .multiThreaded (true) .defaultMaxTotalConnectionPerRoute (2) .maxTotalConnection (10) .build ()); returner fabrik.getObject (); }

Dette opretter en Jest-klient, der er forbundet med en Elasticsearch-klient, der kører lokalt. Mens dette forbindelseseksempel er trivielt, Jest har også fuld understøttelse af proxyer, SSL, godkendelse og endda nodeopdagelse.

Det JestClient klasse er generisk og har kun en håndfuld offentlige metoder. Den vigtigste, vi bruger, er udføre, som tager en instans af Handling interface. Jest-klienten leverer flere builder-klasser til at skabe forskellige handlinger, der interagerer med Elasticsearch.

Resultatet af alle Jest-opkald er en forekomst af JestResult. Vi kan tjekke for succes ved at ringe erSucceded. For mislykkede handlinger kan vi ringe getErrorMessage for at få flere detaljer:

JestResult jestResult = jestClient.execute (ny Delete.Builder ("1"). Indeks ("medarbejdere"). Build ()); hvis (jestResult.isSucceeded ()) {System.out.println ("Succes!"); } andet {System.out.println ("Fejl:" + jestResult.getErrorMessage ()); }

3.1. Håndtering af indekser

For at kontrollere, om der findes et indeks, bruger vi Indeks eksisterer handling:

JestResult resultat = jestClient.execute (nye IndicesExists.Builder ("medarbejdere"). Build ()) 

For at oprette et indeks bruger vi CreateIndex handling:

jestClient.execute (ny CreateIndex.Builder ("medarbejdere"). build ());

Dette opretter et indeks med standardindstillinger. Vi kan tilsidesætte specifikke indstillinger under oprettelse af indeks:

Kortindstillinger = nyt HashMap (); settings.put ("number_of_shards", 11); settings.put ("antal_af_replikas", 2); jestClient.execute (ny CreateIndex.Builder ("medarbejdere"). indstillinger (indstillinger) .build ());

Og det er også simpelt at oprette eller ændre aliasser ved hjælp af ModifyAliases handling:

jestClient.execute (ny ModifyAliases.Builder (ny AddAliasMapping.Builder ("medarbejdere", "e"). build ()). build ()); jestClient.execute (ny ModifyAliases.Builder (ny FjernAliasMapping.Builder ("medarbejdere", "e"). build ()). build ());

3.2. Oprettelse af dokumenter

Jest-klienten gør det let at indeksere - eller oprette - nye dokumenter ved hjælp af Indeks handlingsklasse. Dokumenter i Elasticsearch er kun JSON-data, og der er flere måder at videregive JSON-data til Jest-klienten til indeksering.

Lad os i dette eksempel bruge et imaginært medarbejderdokument:

{"name": "Michael Pratt", "title": "Java Developer", "skills": ["java", "spring", "elasticsearch"], "yearsOfService": 2}

Den første måde at repræsentere et JSON-dokument på er ved hjælp af en Java Snor. Mens vi manuelt kan oprette JSON-strengen, skal vi være opmærksomme på korrekt formatering, seler og undslippe citattegn.

Derfor er det lettere at bruge et JSON-bibliotek som Jackson til at opbygge vores JSON-struktur og derefter konvertere til en Snor:

ObjectMapper-kortlægger = ny ObjectMapper (); JsonNode-medarbejderJsonNode = mapper.createObjectNode () .put ("navn", "Michael Pratt") .put ("title", "Java Developer") .put ("yearsOfService", 2) .set ("skills", mapper. createArrayNode () .add ("java") .add ("spring") .add ("elasticsearch")); jestClient.execute (ny Index.Builder (medarbejderJsonNode.toString ()). indeks ("medarbejdere"). build ());

Vi kan også bruge en Java Kort at repræsentere JSON-data og videregive dem til Indeks handling:

Kortlæg medarbejderHashMap = nyt LinkedHashMap (); medarbejderHashMap.put ("navn", "Michael Pratt"); medarbejderHashMap.put ("titel", "Java Developer"); medarbejderHashMap.put ("yearsOfService", 2); medarbejderHashMap.put ("skills", Arrays.asList ("java", "spring", "elasticsearch")); jestClient.execute (ny Index.Builder (medarbejderHashMap) .index ("medarbejdere"). build ());

Endelig kan Jest-klienten acceptere enhver POJO, der repræsenterer det dokument, der skal indekseres. Lad os sige, at vi har en Medarbejder klasse:

offentlig klassemedarbejder {Strenge navn; String titel; Liste færdigheder; int yearsOfService; }

Vi kan videregive en forekomst af denne klasse direkte til Indeks Bygger:

Medarbejdermedarbejder = ny medarbejder (); medarbejder.setnavn ("Michael Pratt"); medarbejder.setTitle ("Java Developer"); medarbejder.setYearsOfService (2); medarbejder.setSkills (Arrays.asList ("java", "spring", "elasticsearch")); jestClient.execute (ny Index.Builder (medarbejder) .index ("medarbejdere"). build ());

3.3. Læsning af dokumenter

Der er to primære måder at få adgang til et dokument fra Elasticsearch ved hjælp af Jest-klienten. For det første, hvis vi kender dokument-ID'et, kan vi få adgang til det direkte ved hjælp af Få handling:

jestClient.execute (ny Get.Builder ("medarbejdere", "17"). build ());

For at få adgang til det returnerede dokument skal vi ringe til en af ​​de forskellige getSource metoder. Vi kan enten få resultatet som rå JSON eller deserialisere det tilbage til en DTO:

Medarbejder getResult = jestClient.execute (ny Get.Builder ("medarbejdere", "1"). Build ()) .getSourceAsObject (medarbejder.klasse);

Den anden måde at få adgang til dokumenter er ved hjælp af en søgeforespørgsel, der implementeres i Jest med Søg handling.

Jest-klienten understøtter den fulde Elasticsearch-forespørgsel DSL. Ligesom indekseringsoperationer udtrykkes forespørgsler som JSON-dokumenter, og der er flere måder at udføre søgninger på.

Først kan vi sende en JSON-streng, der repræsenterer søgeforespørgslen. Som en påmindelse skal vi sørge for at sikre, at strengen er korrekt undsluppet og er gyldig JSON:

String search = "{" + "\" query \ ": {" + "\" bool \ ": {" + "\" must \ ": [" + "{\" match \ ": {\" name \ ": \" Michael Pratt \ "}}" + "]" + "}" + "}" + "}"; jestClient.execute (ny Search.Builder (søg) .build ());

Som med Indeks handling ovenfor, kunne vi bruge et bibliotek som Jackson til at opbygge vores JSON-forespørgselsstreng.

Derudover kan vi også bruge den oprindelige Elasticsearch-forespørgselshandlings-API. Den ene ulempe ved dette er, at vores applikation skal afhænge af det fulde Elasticsearch-bibliotek.

Med Søg handling, kan du få adgang til de matchende dokumenter ved hjælp af getSource metoder. Imidlertid, Jest leverer også Hit klasse, der indpakker de matchende dokumenter og giver metadata om resultaterne. Bruger Hit klasse kan vi få adgang til yderligere metadata for hvert resultat: score, routing og forklare resultater for at nævne nogle få:

Liste searchResults = jestClient.execute (ny Search.Builder (søg) .build ()) .getHits (Medarbejder.klasse); searchResults.forEach (hit -> {System.out.println (String.format ("Dokument% s har score% s", hit.id, hit.score);});

3.4. Opdatering af dokumenter

Jest giver en simpel Opdatering handling til opdatering af dokumenter:

medarbejder.setYearOfService (3); jestClient.execute (ny Update.Builder (medarbejder) .index ("medarbejdere"). id ("1"). build ());

Det accepterer de samme JSON-repræsentationer som Indeks handling, vi så tidligere, hvilket gjorde det let at dele kode mellem de to operationer.

3.5. Sletning af dokumenter

Sletning af et dokument fra et indeks sker ved hjælp af Slet handling. Det kræver kun et indeksnavn og dokument-ID:

jestClient.execute (ny Delete.Builder ("17") .index ("medarbejdere") .build ());

4. Bulkoperationer

Jest-klienten understøtter også bulkoperationer. Dette betyder, at vi kan spare tid og båndbredde ved at sende flere operationer sammen på samme tid.

Bruger Masse handling, kan vi kombinere et hvilket som helst antal anmodninger i et enkelt opkald. Vi kan endda kombinere forskellige typer anmodninger sammen:

jestClient.execute (ny Bulk.Builder () .defaultIndex ("medarbejdere") .addAction (ny Index.Builder (medarbejderObject1) .build ()) .addAction (ny Index.Builder (medarbejderObject2) .build ()) .addAction ( ny Delete.Builder ("17"). build ()) .build ());

5. Asynkrone operationer

Jest-klienten understøtter også asynkrone operationer, hvilket betyder, at vi kan udføre en af ​​ovenstående operationer ved hjælp af ikke-blokerende I / O.

For at påkalde en handling asynkront skal du blot bruge executeAsync metode til klienten:

jestClient.executeAsync (ny Index.Builder (medarbejderObject1) .build (), ny JestResultHandler () {@ Override offentlig tomrum afsluttet (JestResult-resultat) {// håndteringsresultat} @ Override offentlig ugyldig mislykkedes (Undtagelse ex) {// undtagelse af håndtering }});

Bemærk, at den asynkrone strøm ud over handlingen (indeksering i dette tilfælde) også kræver en JestResultHandler. Jest-klienten kalder dette objekt, når handlingen er afsluttet. Interfacet har to metoder - afsluttet og mislykkedes - der tillader håndtering af henholdsvis succes eller fiasko af operationen.

6. Konklusion

I denne vejledning har vi kort kigget på Jest-klienten, en RESTful Java-klient til Elasticsearch.

Selvom vi kun har dækket en lille del af dens funktionalitet, er det klart, at Jest er en robust Elasticsearch-klient. Dens flydende builder-klasser og RESTful-grænseflader gør det let at lære, og dets fulde support til Elasticsearch-grænseflader gør det til et alternativ til den oprindelige klient.

Som altid er alle kodeeksemplerne i vejledningen overstået på GitHub.