streamalism.org

1. Introduksjon

Alle som har jobbet med Elasticsearch vet at å bygge spørsmål ved hjelp av RESTful search API kan være kjedelig og feilutsatt.

I denne veiledningen ser vi på Jest, en HTTP Java-klient for Elasticsearch. Mens Elasticsearch tilbyr sin egen native Java-klient, Jest gir et mer flytende API og enklere grensesnitt å jobbe med.

2. Maven avhengighet

Det første vi må gjøre er å importere Jest-biblioteket til POM:

 io.searchbox jest 6.3.1 

Versjonen for Jest følger den for det viktigste Elasticsearch-produktet. Dette bidrar til å sikre kompatibilitet mellom klient og server.

Ved å inkludere Jest-avhengigheten vil det tilsvarende Elasticsearch-biblioteket inkluderes som en transitiv avhengighet.

3. Bruke Jest Client

I denne delen ser vi på å bruke Jest-klienten til å utføre vanlige oppgaver med Elasticsearch.

For å bruke Jest-klienten oppretter vi ganske enkelt en JestClient objektet ved hjelp av JestClientFactory. Disse objektene er dyre å lage og er trådsikre, så vi lager en singleton-forekomst som kan deles gjennom hele søknaden vår:

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

Dette vil opprette en Jest-klient koblet til en Elasticsearch-klient som kjører lokalt. Selv om dette forbindelseseksemplet er trivielt, Jest har også full støtte for proxyer, SSL, autentisering og til og med nodeoppdagelse.

De JestClient klassen er generisk og har bare en håndfull offentlige metoder. Den viktigste vi skal bruke er henrette, som tar en forekomst av Handling grensesnitt. Jest-klienten tilbyr flere byggeklasser for å skape forskjellige handlinger som samhandler med Elasticsearch.

Resultatet av alle Jest-samtaler er en forekomst av JestResult. Vi kan se etter suksess ved å ringe er vellykket. For mislykkede handlinger kan vi ringe getErrorMessage for å få mer detaljer:

JestResult jestResult = jestClient.execute (ny Delete.Builder ("1"). Indeks ("ansatte"). Build ()); hvis (jestResult.isSucceeded ()) {System.out.println ("Suksess!"); } annet {System.out.println ("Feil:" + jestResult.getErrorMessage ()); }

3.1. Administrere indekser

For å sjekke om det finnes en indeks, bruker vi IndicesExists handling:

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

For å lage en indeks bruker vi CreateIndex handling:

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

Dette vil opprette en indeks med standardinnstillinger. Vi kan overstyre bestemte innstillinger under indeksoppretting:

Kartinnstillinger = nytt HashMap (); settings.put ("number_of_shards", 11); settings.put ("number_of_replicas", 2); jestClient.execute (nye CreateIndex.Builder ("ansatte"). innstillinger (innstillinger) .build ());

Og å opprette eller endre aliaser er også enkelt å bruke ModifyAliases handling:

jestClient.execute (nye ModifyAliases.Builder (nye AddAliasMapping.Builder ("ansatte", "e"). build ()). build ()); jestClient.execute (nye ModifyAliases.Builder (nye RemoveAliasMapping.Builder ("ansatte", "e"). build ()). build ());

3.2. Opprette dokumenter

Jest-klienten gjør det enkelt å indeksere - eller opprette - nye dokumenter ved hjelp av Indeks actionklasse. Dokumenter i Elasticsearch er bare JSON-data, og det er flere måter å overføre JSON-data til Jest-klienten for indeksering.

For dette eksemplet, la oss bruke et imaginært medarbeiderdokument:

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

Den første måten å representere et JSON-dokument på er å bruke Java String. Mens vi kan opprette JSON-strengen manuelt, må vi være oppmerksomme på riktig formatering, bukseseler og rømmingstegn.

Derfor er det lettere å bruke et JSON-bibliotek som Jackson til å bygge vår JSON-struktur og deretter konvertere til en String:

ObjectMapper mapper = ny ObjectMapper (); JsonNode-ansattJsonNode = 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 (medarbeiderJsonNode.toString ()). indeks ("ansatte"). build ());

Vi kan også bruke Java Kart å representere JSON-data og overføre det til Indeks handling:

Kartlegg medarbeiderHashMap = nytt LinkedHashMap (); ansatteHashMap.put ("navn", "Michael Pratt"); medarbeiderHashMap.put ("tittel", "Java-utvikler"); ansatteHashMap.put ("yearsOfService", 2); employeeHashMap.put ("skills", Arrays.asList ("java", "spring", "elasticsearch")); jestClient.execute (ny Index.Builder (ansatteHashMap) .index ("ansatte"). build ());

Til slutt kan Jest-klienten godta hvilken som helst POJO som representerer dokumentet som skal indekseres. La oss si at vi har en Ansatt klasse:

offentlig klasse ansatt {strengnavn; Stringtittel; Liste ferdigheter; int yearsOfService; }

Vi kan sende en forekomst av denne klassen direkte til Indeks bygger:

Ansatt ansatt = ny ansatt (); ansatte.setName ("Michael Pratt"); ansatte.setTitle ("Java Developer"); ansatt.setYearsOfService (2); ansatte.setSkills (Arrays.asList ("java", "spring", "elasticsearch")); jestClient.execute (ny Index.Builder (ansatt) .index ("ansatte"). build ());

3.3. Lese dokumenter

Det er to primære måter å få tilgang til et dokument fra Elasticsearch ved hjelp av Jest-klienten. Først, hvis vi kjenner dokument-ID-en, kan vi få tilgang til den direkte ved hjelp av Få handling:

jestClient.execute (nye Get.Builder ("ansatte", "17"). build ());

For å få tilgang til det returnerte dokumentet, må vi ringe en av de forskjellige getSource metoder. Vi kan enten få resultatet som rå JSON eller deserialisere det tilbake til en DTO:

Medarbeider getResult = jestClient.execute (ny Get.Builder ("ansatte", "1"). Build ()) .getSourceAsObject (Employee.class);

Den andre måten å få tilgang til dokumenter er å bruke et søk, som er implementert i Jest med Søk handling.

Jest-klienten støtter hele Elasticsearch-spørringen DSL. På samme måte som indekseringsoperasjoner, blir spørsmål uttrykt som JSON-dokumenter, og det er flere måter å utføre søk på.

Først kan vi sende en JSON-streng som representerer søket. Som en påminnelse må vi passe på å sikre at strengen slipper riktig og er gyldig JSON:

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

Som med Indeks handling ovenfor, kan vi bruke et bibliotek som Jackson til å bygge vår JSON-spørringsstreng.

I tillegg kan vi også bruke den opprinnelige API-en for søkehandling. Den ene ulempen med dette er at applikasjonen vår må avhenge av hele Elasticsearch-biblioteket.

Med Søk handling, kan du få tilgang til samsvarende dokumenter ved hjelp av getSource metoder. Derimot, Jest gir også Truffet klasse, som bryter de samsvarende dokumentene og gir metadata om resultatene. Bruker Truffet klasse, kan vi få tilgang til flere metadata for hvert resultat: score, ruting og forklare resultater, for å nevne noen:

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

3.4. Oppdatere dokumenter

Jest gir en enkel Oppdater handling for oppdatering av dokumenter:

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

Den godtar de samme JSON-representasjonene som Indeks handling vi så tidligere, noe som gjør det enkelt å dele kode mellom de to operasjonene.

3.5. Slette dokumenter

Slette et dokument fra en indeks gjøres ved hjelp av Slett handling. Det krever bare et indeksnavn og dokument-ID:

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

4. Masseoperasjoner

Jest-klienten støtter også bulkoperasjoner. Dette betyr at vi kan spare tid og båndbredde ved å sende flere operasjoner samtidig.

Bruker Bulk handling, kan vi kombinere et hvilket som helst antall forespørsler i en enkelt samtale. Vi kan til og med kombinere forskjellige typer forespørsler sammen:

jestClient.execute (ny Bulk.Builder () .defaultIndex ("ansatte") .addAction (ny Index.Builder (medarbeiderObject1) .bygg ()) .addAksjon (ny Indeks.Bygger (ansattObject2) .bygg ()) .addAksjon ( ny Delete.Builder ("17"). build ()) .build ());

5. Asynkrone operasjoner

Jest-klienten støtter også asynkrone operasjoner, noe som betyr at vi kan utføre noen av de ovennevnte operasjonene ved hjelp av ikke-blokkerende I / O.

For å påkalle en operasjon asynkront, bruk bare executeAsync metoden til klienten:

jestClient.executeAsync (ny Index.Builder (medarbeiderObject1) .bygg (), ny JestResultHandler () {@ Override offentlig tomrom fullført (JestResult resultat) {// håndteringsresultat} @ Override offentlig tomrom mislyktes (unntak eks) {// håndtak unntak }});

Merk at i tillegg til handlingen (indeksering i dette tilfellet), krever den asynkrone strømmen også en JestResultHandler. Jest-klienten vil kalle dette objektet når handlingen er ferdig. Grensesnittet har to metoder - fullført og mislyktes - som tillater håndtering av henholdsvis suksess eller fiasko av operasjonen.

6. Konklusjon

I denne opplæringen har vi sett kort på Jest-klienten, en RESTful Java-klient for Elasticsearch.

Selv om vi bare har dekket en liten del av funksjonaliteten, er det klart at Jest er en robust Elasticsearch-klient. De flytende byggeklasser og RESTful-grensesnitt gjør det enkelt å lære, og den fulle støtten for Elasticsearch-grensesnitt gjør det til et godt alternativ til den opprinnelige klienten.

Som alltid er alle kodeeksemplene i opplæringen over på GitHub.