Text+ Resource and Search Integration Hackathon

Erik Körner <koerner@saw-leipzig.de>

Begrüßung und Überblick

Agenda Donnerstag (16.11.2023)

9:00 Uhr

Vortrag: Einführung in die Föderierte Inhaltssuche

10:30 Uhr

Teilnehmer: Vorstellung Projekte und Ressourcen

12:00 Uhr

Mittagspause

13:00 Uhr

Vortrag: Implementierung und Query Translation

15:30 Uhr

Coding-Session

20:00 Uhr

Get-together

Agenda Freitag (17.11.2023)

9:00 Uhr

Coding-Session

12:00 Uhr

Mittagspause

13:00 Uhr

Coding-Session

14:00 Uhr

Teilnehmer: Präsentation der Ergebnisse

15:00 Uhr

Ende

Ziel des Workshop

  • Verständnis von der FCS und der technischen Infrastruktur

  • Kenntnisse zu Referenzbibliotheken und Werkzeugen

  • Aufbau eigener FCS Endpunkte

    • Entwicklung

    • Debug und Deployment

    • Test mit Validator & Integration in Aggregator

  • Präsentation im gemeinsamen Aggregator?

Über mich

  • Erik Körner

  • Master Informatik, PhD, Schwerpunkt NLP

  • Studium an der Universität Leipzig …

    … Wiss. Mitarbeiter an der Universität Leipzig, ASV …

    … aktuell im Projekt Text+ an der SAW

  • seit Mitte 2022 Arbeit mit und an FCS im Rahmen von Text+

  • seit 2023 offiziell Maintainer für FCS in CLARIN-ERIC

Text+

  • NFDI-Konsortium zum Aufbau einer auf Sprach- und Textdaten ausgerichteten Forschungsdateninfrastruktur

  • ungefähr 30 beteiligte Institutionen:

    • Akademien

    • Universitäten

    • Bibliotheken

    • Archive

    • Stiftungen

  • Start 10/2021

Text+ Überblick

Text+ – Struktureller Aufbau

Text+ Überblick

CLARIN-ERIC

  • CLARIN = Common Language Resources and Technology Infrastructure

  • ERIC = European Research Infrastructure Consortium

  • verteilte digitale Forschungsinfrastruktur

  • teilnehmende Zentren aus Europa und darüber hinaus

  • Universitäten, Forschungszentren, Bibliotheken und Archive

  • gegründet 2012

Text+ Überblick

CLARIN-ERIC

  • unterstützt Forschung in den Geistes- und Sozialwissenschaften

  • einfacher und nachhaltiger Zugriff auf multimodale digitale Sprachdaten (Text, Audio, Video) und fortschrittliche Tools (Datensätze erkunden, analysieren, kombinieren)

  • interoperable Tools und Daten → Datensammlungen können kombiniert und Tools aus verschiedenen Quellen verkettet werden, um unabhängig von ihrem Standort Operationen unterschiedlicher Komplexität auszuführen

  • basierend auf standardisierten Schnittstellen und Kommunikationsprotokollen

Einführung in die Föderierte Inhaltssuche (FCS)

Was ist die FCS?

  • “Federated Content Search” von CLARIN

    übersetzt: Inhaltssuche über verteilte Ressourcen

    auch: Föderierte “Corpus Query Platform”

  • Suche nach Mustern in verteilten Text-Sammlungen

  • kein zentraler Index!

  • Text-Ressourcen umfassen annotierte Korpora, Volltexte usw.

  • FCS = Interface-Spezifikation, Such-Infrastruktur und Software-Ökosystem

  • Nutzung von etablierten Standards und Erweiterbarkeit!

Was umfasst die FCS?

Interface-Spezifikation

  • Beschreibung von Suchprotokoll (Anfragesprache, Formate und Kommunikationswege) “für homogenen Zugriff auf heterogene Suchmaschinen”

  • RESTful Protokoll

Such-Infrastruktur in CLARIN und Text+

  • zentraler Client (Daten “Aggregator” und Webportal)

  • dezentrale Endpunkte an den Datenzentren (lokale Suchmaschinen auf Ressourcen)

Was umfasst die FCS? (2)

Software-Ökosystem primär in Java

  • Bibliotheken (Java, Python, …)

  • Tools (Validator, Aggregator, Registry)

Voraussetzungen zur Teilnahme an der FCS

  • (eigene) Text-Ressourcen

  • Such-“Maschine” auf Text-Ressourcen

    • Minimum: Volltextsuche

  • Deployment von FCS-Endpunkt mit öffentlichem Zugriff

Vor- und Nachteile für die FCS

Vorteile

  • Integration vieler Ressourcen, Verknüpfung und Vergleich von Ergebnissen

  • Integration mit anderen Tools (Weblicht, Registry/VLO, Switchboard, …)

  • gleiche Querys, Formate, Präsentation

  • keine doppelte Datenhaltung, Inkonsistenz

Nachteile

  • keine Kontrolle über Ressourcen

  • keine deterministischen Ergebnisse (z.B. Links für Publikationen)

  • kein globales Ranking von Ergebnissen möglich

Vor- und Nachteile für die FCS Endpunkte

Vorteile

  • Kontrolle über Ressourcen und Suche (Ranking, Fuzzy, …)

  • keine Duplication von Daten durch zentralen Index

  • erhöhte Sichtbarkeit in größerem Ressourcenkatalog

Nachteile

  • Deployment von (extra) Endpoint notwendig

Vergleich FCS mit zentralem Index

Daten

➕ bei Endpunkten

➖ doppelte Datenhaltung, mögliche Inkonsistenz (Alter, Änderungen); rechtlich evtl. keine Weitergabe möglich

Daten-Updates

➕ Endpunkte können schnell reagieren

➖ schwierig, z.B. Entfernen von Ressourcen bei rechtlichen Problemen; Updates mit längeren Zeiten verbunden, falls überhaupt möglich

Vergleich FCS mit zentralem Index (2)

Globales Ranking

➖ sehr schwierig/unmöglich

➕ gut möglich (?), vermutlich implizite Annahme zu und Normalisierung von Daten für Indizierung

Facettierung

➖ schwierig (z.B. über externe Metadaten; nicht direkt vorgesehen)

➕ Indizierung erlaubt Clustering/Klassifikation nach Themen und Kategorien

Geschichte

  • ~ 2011 als Working Group in CLARIN gestartet

  • Mai 2011 EDC/FCS Workshop

  • ~ 2011–2013 Initiale Version, nun als FCS “Legacy” benannt

    • SRU Scan für Ressourcen, BASIC Search (CQL/Volltext), KWIC

  • April 2013 FCS Workshop

  • ~ 2013/2014 Code und Spec für FCS Core 1.0

    • fcs-simple-endpoint 1.0.0, sru-server 1.5.0

    • BASIC Hits Data View, keine scan Operation mehr

  • ~ 2015/2016 Spec und Code für FCS Core 2.0

    • fcs-simple-endpoint 1.3.0, sru-server 1.8.0

    • Advanced Data Views (FCS-QL), …

  • 2022 FCS Schwerpunkt in Text+ (Findability)

  • 2023 neuer FCS-Maintainer in CLARIN

Kommunikationsprotokoll

SRU (Search/Retrieval via URL) / OASIS searchRetrieve

  • Standardisiert durch Library of Congress (LoC) / OASIS

    • RESTful

    • Explain: Vorhandene Ressourcen

      • Sprache, Annotationen, unterstützte Datenformate etc.

    • SearchRetrieve: Suchanfrage

  • Daten als XML

  • Erlaubt Erweiterungen des Protokolls

Grundannahme zur Datenstruktur

  • verschiedene (optionale) Annotationsebenen (Layer)

Volltext

Die

Autos

sind

schnell

Wortart

DET

NOUN

VERB

ADJ

Grundform

Das

Auto

ist

schnell

Phonetische Transkription

…​

…​

…​

…​

Orthographische Transkription

…​

…​

…​

…​

[…​]

Explain: Ressourcen-Discovery

Endpoint Description

Explain: Ressourcen-Discovery (2)

Endpoint Description

Explain: Ressourcenstruktur

Endpoint Description

Anfragesprache FCS-QL

  • Orientiert sich an CQP

  • Unterstützt verschiedene Annotationslayer

Visual Query Builder for FCS-QL

Ergebnisvisualisierung

HITS Results

Ergebnisvisualisierung (2)

KWIC Results

Ergebnisvisualisierung (3)

ADV Results

Aktueller Stand der FCS

Aktuelle Arbeiten

  • Lexical Resources Erweiterung

    • erste Spezifikation und Implementierung in Text+

    • Offizielle Erweiterung von CLARIN → ~2024 Working Plan

  • AAI-Einbindung

    • Spezifikation und Implementierung

    • Ziel: Unterstützung zugangsbeschränkte Ressourcen

    • Absicherung des Aggregators über Shibboleth → Weitergabe von AAI-Attributen an Endpunkte

    • Vorarbeit aus CLARIAH-DE, Teil des Text+ Arbeitsplans (IDS Mannheim, Uni/SAW Leipzig, Vorarbeiten BBAW)

  • Syntactic Search (?)

  • Größerer Bedarf an föderierten Suchverfahren für Textressourcen in Text+ (Editionen, Collections)

Aktueller Stand bzgl. Lexical Resources

  • CLARIN-EU Taskforce

  • Arbeitsplan CLARIN ERIC: „extending the protocol to cover additional data types (e.g. lexica) will be explored“

    • im CLARIN 2024 Working Plan

  • Interessensbekundungen aus verschiedenen Ländern

  • Erste Vorarbeiten: „RABA“ (Estland): u.a. „Eesti Wordnet“

Aktueller Stand bzgl. Lexical Resources

Aktueller Stand von Teilnehmenden

CLARIN (contentsearch.clarin.eu, Registry)

  • 209 Ressourcen (94 in Advanced)

    in 61 Sprachen

    von 20 Institutionen in 12 Ländern

Text+ (fcs.text-plus.org)

  • 53 Ressourcen (17 in Advanced, 30 Lexical)

    in 6 Sprachen

    von 9 Institutionen in Deutschland

Integration in FCS Infrastruktur

Text+

  • Side-Loading im Aggregator

  • WIP: Registry (Verzeichnis von Endpunkten)

CLARIN

  • Alpha/Beta über Side-Loading in den Aggregator

  • Stable/Long-Term: Eintrag in Centre Registry

    • CLARIN Account + Formular als Centre

    • damit auch Monitoring etc.

Weitere Nutzung der FCS

  • Entwicklung eines alternativen Aggregator-Frontends als Web Component

Bootstrapping Endpunkt Entwicklung

Wegweiser Endpunktentwicklung

Entwicklungsentscheidungen

❓ Kann ich Endpunkt selber hosten?

❗ nein → HelpDesk: CLARIN, Text+

❓ Welche Art von Daten besitze ich?

❗ Rohtext, Vertical/CONLL, TEI, …

❓ Welche Suchmaschine nutze ich / kann ich nutzen?

❗ KorAP, Korp/CWB, Lucene/Solr/ElasticSearch, (No)SketchEngine, …

Entwicklungsentscheidungen (2)

❓ Anpassung oder Neuentwicklung?

❗ Liste bestehender Endpunkt-Implementierungen (Awesome List)

❓ Programmiersprache?

❗ Java, Python, (PHP, XQuery)

❓ Eigenentwicklung: Nutzung der Referenzbibliotheken (Java, Python)

❗ Maven Archetype, Korp

❗ SRU + FCS Spezifikationen …

Endpunkt-Implementierungen

Quelle: clarin, awesome-fcs

Endpunktneuentwicklung

Endpunktneuentwicklung (2)

Voraussetzung an lokale Suchmaschine

❗ Volltextsuche

❓ mit Treffer-Markierung

❓ Corpus-Suche (Annotationen über segmentiertem Text)

❕ Pagination (Gesamt-Trefferzahl)

❗ Ressourcen-PID

❓ Verlinkung auf Ergebnisseiten

Technische Grundlagen

Disclaimer

Fokus primär auf:

  • Version: FCS Core 2.0; maximal Kompatibilität mit FCS Core 1.0

  • SRU Server, FCS Endpunkt; nicht FCS Client-Anwendungen

  • Nutzung der Referenzbibliotheken

    → Java und Python

  • Mögliche Nutzung bestehender Endpunkte

Kein:

  • Durcharbeiten der Spezifikation; nur die wesentlichen Informationen

  • Neuentwicklung von SRU/FCS Protokollen, Bibliotheken etc.

    (z.B. in anderen Sprachen)

SRU – Geschichte

SRU: Search/Retrieve via URL → LOC

  • ursprünglich bei der Library of Congress (LOC) entwickelt

    2004: SRU 1.1 - LOC

    2007: SRU 1.2 - LOC

  • ab SRU 2.0 standardisiert bei OASIS [1] als “searchRetrieve Version 1.0 OASIS Standard”

    2013: SRU 2.0 - LOC, OASIS (OASIS Ankündigung)

    Erweiterung von SRU 1.2 → Unterschiede zu SRU 1.2 (LOC)

1. OASIS: Organization for the Advancement of Structured Information Standards

searchRetrieve Version 1.0 – OASIS Standard

  • Part 0. Overview Version 1.0

  • Part 1. Abstract Protocol Definition Version 1.0

  • Part 2. SRU searchRetrieve Operation: APD Binding for SRU 1.2 Version 1.0

  • Part 3. SRU searchRetrieve Operation: APD Binding for SRU 2.0 Version 1.0

  • Part 4. APD Binding for OpenSearch 1.0 version 1.0

  • Part 5. CQL: The Contextual Query Language version 1.0

  • Part 6. SRU Scan Operation version 1.0

  • Part 7. SRU Explain Operation version 1.0

searchRetrieve: Part 0. – Overview Version 1.0

SRU (SRU: Search/Retrieve via URL) is a web service protocol supported over both SOAP and REST for client-server based search. SRU1.x was developed as a web service replacement for the NISO Z39.50 protocol. SRU2.0 is a revision to SRU which as well as including many enhancements to SRU1.2 was developed alongside the APD.

For the SRU protocol model, three operations are defined as part of its Processing Model:

  • SearchRetrieve Operation. The actual SearchRetrieve operation defined by the SRU protocol; A SearchRetrieve operation consists of a SearchRetrieve request from client to server followed by a SearchRetrieve response from server to client.

  • Scan Operation. Similar to SRU, the Scan protocol defines a request message and a response message for iterating through available search terms. a Scan operation consists of a Scan request followed by a Scan response.

  • Explain Operation. Every SRU or scan server provides an associated Explain document as part of its Description and Discovery Model, providing information about the server’s capabilities. A client may retrieve this document and use the information to self-configure and provide an appropriate interface to the user. When a client retrieves an Explain document, this constitutes an Explain operation.

searchRetrieve – APD und Bindings

  • Abstract Protocol Definition (APD) für “searchRetrieve operation”

    • Modell für die SearchRetrieve Operation

    • beschreibt Capabilities und generelle Charakteristiken von einem Server oder Suchmaschine, sowie wie der Zugriff ablaufen soll

    • definiert abstrakte Request Parameter und Response Elemente

  • Binding

    • beschreibt korrespondierende Namen der Parameter und Elemente

    • statisch (für Mensch), dynamisch (Maschine), …

    • Bindings: SRU 1.2, SRU 2.0, (OpenSearch)

    • Beispiele: “startPosition” (APD) → “startRecord” (SRU 2.0)

      “recordPacking” (SRU 1.2) → “recordXMLEscaping” (SRU 2.0)

searchRetrieve – APD Abstrakte Modelle

Data Model
Beschreibung der Daten, auf denen die Suche ausgeführt werden soll

Query Model
Beschreibung der Konstruktion von Search Querys

Processing Model
Beschreibung, wie Query von Client zum Server gesendet wird

Result Set Model
Struktur der Ergebnisse einer Suche

Diagnostics Model
Beschreibung, wie Fehler vom Server dem Client mitgeteilt werden

Description and Discovery Model
Beschreibung, zur Discovery des “Search Service”, Selbstbeschreibung von Funktionalität des Services

SRU 2.0 – Operation Model

  • SRU Anfrage (Client → Server) mit Antwort (Server → Client)

  • Operationen

    • SearchRetrieve

    • Scan

    • Explain

SRU 2.0 – Data Model

  • Server = Datenbank für Client für Search/Retrieval

  • Datenbank = Sammlung von Units of Data → Abstract Record

  • Abstract Records (oder Response Records) mit einem/mehreren Formaten durch Server

  • Format (oder Item Type) = Record Schema

SRU 2.0 – Protocol Model

  • HTTP GET

    • Parameter kodiert als “key=value”

    • UTF-8

    • %-Escaping

    • Trennung an “?”, “&”, “=”

  • HTTP POST

    • application/x-www-form-urlencoded

    • kein Character-Encoding notwendig

    • keine Längenbeschränkung

  • HTTP SOAP (?)

SRU Protocol

SRU 2.0 – Processing Model

  • “Anfragebearbeitung am Server”

  • Request

    • Anzahl an Records

    • Identifier für Record Schema (→ Records in Response)

    • Identifier für Response Schema (→ ganze Response)

  • Response

    • Records in Result Set

    • Diagnostic Information

    • Result Set Identifier für Anfragen zu weiteren Ergebnissen

SRU 2.0 – Query Model

  • jede “angemessene Anfragesprache” kann genutzt werden

  • verpflichtende Unterstützung von

    “Contextual Query Language” (CQL)

SRU 2.0 – Parameter Model

  • Nutzung von Parametern, einige durch SRU 2.0 vordefiniert

  • auch nicht im Protokoll festgelegte Parameter sind erlaubt

  • Parameter “query”

    • in jeder Anfrage irgendwie enthalten (“query” oder durch Parameter nicht definiert im Protokoll)

    • Query mit “queryType” (default “cql”)

SRU 2.0 – Result Set Model

  • Logisches Modell → “Result Sets” sind nicht verpflichtend

  • Query → Auswahl passender Records

    • geordnete Liste, nicht-modifizierbares Set nach Erstellung

    • Sortierung/Ordnung bestimmt durch Server

  • für Client:

    • Menge abstrakter Records, Nummerierung beginnt mit 1

    • jeder Record kann in eigenen Format angefragt werden

    • einzelne Records können “verschwinden”, keine Neuordnung im Result Set durch Server, jedoch Diagnostic

SRU 2.0 – Diagnostic Model

  • fatal

    • Ausführung der Anfrage kann nicht beendet werden

    • z.B. invalider Query

  • non-fatal

    • Verarbeitung beeinträchtigt, aber Anfrage kann beendet werden

    • z.B. einzelne Records sind nicht im angefragten Schema verfügbar, Server sendet nur die verfügbaren und informiert über den Rest

    • surrogate

      • für einzelne Records

    • non-surrogate

      • alle Records sind verfügbar, aber etwas ging schief, z.B. Sortierung

      • oder z.B. auch einfach eine Warnungen

SRU 2.0 – Explain Model

  • muss für HTTP GET über die Base URL des SRU Servers verfügbar sein

  • → Server Capabilities

  • im Client zur Selbstkonfiguration und um entsprechendes User-Interface anzubieten

  • Details zu unterstützten Query-Typen, CQL Context Sets, Diagnostic Sets Records Schemas, Sortierungsmöglichkeiten, Defaults, …

SRU 2.0 – Serialization Model

  • kein Beschränkung der Serialisierung von Antworten

    (gesamte Nachricht oder der Records)

  • nicht-XML ist möglich

searchRetrieve 2.0 – Request Parameter

  • alle Parameter sind optional, non-repeatable

  • query, startRecord, maximumRecords, recordXMLEscaping, recordSchema, resultSetTTL, stylesheet; Extension parameters

  • neu in 2.0: queryType, sortKeys, renderedBy, httpAccept, responseType, recordPacking; Facet Parameters

searchRetrieve 2.0 – Response Elements

  • alle Elemente sind optional, by default non-repeatable

  • numberOfRecords, resultSetId, records, nextRecordPosition, echoedSearchRetrieveRequest, diagnostics, extraResponseDataⓇ

  • neu in 2.0: resultSetTTL, resultCountPrecisionⓇ, facetedResultsⓇ, searchResultAnalysisⓇ

    (Ⓡ = repeatable)

searchRetrieve 2.0 – Query

  • query (Parameter)

    • Query

    • Pflicht, wenn keine Angabe von queryType

  • queryType (Parameter, SRU 2.0)

    • optional, by default “cql”

    • Query Typen müssen im Explain gelistet werden, mit URL zur Definition und Nutzungskürzel

    • Reserviert

      • cql

      • searchTerms (Verarbeitung ist Server überlassen, < SRU 2.0)

searchRetrieve 2.0 – Query (Examples)

searchRetrieve 2.0 – Pagination

  • Anfrage zu Ergebnisbereich von startRecord mit maximal maximumRecords

  • startRecord (Parameter)

    • optional, positiver Integer, beginnend mit 1

  • maximumRecords (Parameter)

    • optional, nicht-negativer Integer

    • Server wählt Default, wenn nicht angegeben

    • Server kann mit weniger Records antworten, niemals mehr

searchRetrieve 2.0 – Pagination (2)

  • Antwort mit Gesamtzahl (numberOfRecords) von Records im Result Set, mit Offset (nextRecordPosition) zu nächsten Ergebnissen

  • numberOfRecords (Element)

    • Anzahl von Ergebnissen im Result Set

    • falls Query fehlschlägt, muss es “0” sein

  • nextRecordPosition (Element)

    • Zähler für nächstes Result Set, falls letzter Record in der Response nicht letzter im Result Set ist

    • falls keine weiteren Records, dann darf dieses Element nicht erscheinen

searchRetrieve 2.0 – Result Set

  • resultSetId (Element)

    • optional, Identifier für das Result Set, für Referenzierung in folgenden Anfragen

  • resultSetTTL (Parameter / Element, SRU 2.0 für Element)

    • optional, in Sekunden

    • in Anfrage von Client, wann Result Set nicht mehr genutzt wird

    • in Antwort vom Server, wie lange Result Set verfügbar ist (“good-faith estimate”, → länger oder kürzer möglich)

  • resultCountPrecision (Element, SRU 2.0)

    • URI: “info:srw/vocabulary/resultCountPrecision/1/…”

    • exact / unknown / estimate / maximum / minimum / current

searchRetrieve 2.0 – Pagination (Cont.)

Response XML für CQL Suche nach "cat"

searchRetrieve 2.0 – Serialization

  • recordXMLEscaping (Parameter, SRU 2.0)

    • wenn Records als XML serialisiert werden, kann bei “string” der Records escaped werden (“<”, “>”, “&”); default ist “xml” als direkte Einbettung der Records in die Response, z.B. für Stylesheets

  • recordPacking (Parameter, SRU 2.0)

    • hatte in SRU 1.2 die Semantic von recordXMLEscaping

    • “packed” (default), Server soll Records mit angefragten Schema liefern; “unpacked”, Server kann Stelle der Anwendungsdaten in den Records selber bestimmen (?)

searchRetrieve 2.0 – Serialization (2)

  • httpAccept (Parameter, SRU 2.0)

    • Schema für Response, default ist “application/sru+xml”

  • responseType (Parameter)

    • Schema für Response (in Kombination mit httpAccept)

  • recordSchema (Parameter)

  • records (Element)

    • enthält Records / Surrogate Diagnostics

    • nach default Schema eine Liste von “<record>” Elementen

searchRetrieve 2.0 – Serialization (3)

  • stylesheet (Parameter)

    • URL zu Stylesheet, zur Darstellung beim Nutzer

    • renderedBy (Parameter, SRU 2.0)

    • wo wird Stylesheet für Antwort gerendert

    • “client” (default), URL von stylesheet-Parameter wird einfach wiedergegeben → “thin client” (im Web Browser)

    • “server”, Server soll default SRU Response mit Stylesheet transformieren (z.B. für httpAccept mit HTML-Format)

searchRetrieve 2.0 – Serialization (4)

searchRetrieve 2.0 – Nicht supportete Parameter

  • Sortierung (sortKeys) und Facettierung nicht supported

SRU 2.0 – Extensions

  • Erweiterungen möglich in

    • Anfrage über Extension Parameter

    • (beginnend mit “x-” und Namespace-Identifier, z.B. “x-fcs-”)

  • Antwort im “<extraResponseData>” Element

  • Antwort mit extraResponseData, nur wenn in Anfrage mit entsprechendem Parameter angefragt, nie freiwillig

    • Server kann die Anfrage aber ignorieren, keine Verpflichtung

  • unbekannte Extension-Parameter sind zu ignorieren

SRU 2.0 – Rückwärtskompatibilität

  • Parameter “operation” und “version” von SRU 1.1/SRU 1.2 entfernt → Annahme, pro Version eigener Endpunkt

  • Heuristik

    • searchRetrieve = query oder queryType Parameter

    • scan = scanClause Parameter

    • explain

  • Interoperabilität mit älteren Versionen:

    • Nutzung von operation/version → SRU < 2.0

    • Achtung bei Parametern mit veränderter Semantik

      insbesondere recordPacking

SRU 2.0 – Diagnostics

  • “Fehlerbehandlung”

  • Unterscheidung in (non-)fatal, (non-)surrogate → SRU 2.0 – Diagnostic Model

  • Schema: info:srw/schema/1/diagnostics-v1.1

    Prefix: info:srw/diagnostic/1/

    • uri (ID), details (Zusatzinfos, abhängig von Diagnostic), message

  • Infos:

  • Kategorien: General (1-9), CQL (10-49), Result Sets (50-60), Records (61-74), Sorting (80-96), Explain (100-102), Stylesheets (110-111), Scan (120-121)

  • keine Begrenzung nur auf diese Liste, eigene Diagnostics möglich

SRU 2.0 – Diagnostics (Table)

1

General system error

Debugging information (traceback)

2

System temporarily unavailable

3

Authentication error

4

Unsupported operation

5

Unsupported version

Highest version supported

6

Unsupported parameter value

Name of parameter

7

Mandatory parameter not supplied

Name of missing parameter

8

Unsupported parameter

Name of the unsupported parameter

9

Unsupported combination of parameters

10

Query syntax error

23

Too many characters in term

Length of longest term

26

Non special character escaped in term

Character incorrectly escaped

35

Term contains only stopwords

Value

37

Unsupported boolean operator

Value

38

Too many boolean operators in query

Maximum number supported

47

Cannot process query; reason unknown

48

Query feature unsupported

Feature

60

Result set not created: too many matching records

Maximum number

61

First record position out of range

64

Record temporarily unavailable

65

Record does not exist

66

Unknown schema for retrieval

Schema URI or short name

67

Record not available in this schema

Schema URI or short name

68

Not authorized to send record

69

Not authorized to send record in this schema

70

Record too large to send

Maximum record size

71

Unsupported recordXMLEscaping value

80

Sort not supported

110

Stylesheets not supported

111

Unsupported stylesheet

URL of stylesheet

FCS Interface Specification

FCS Architektur

  • FCS = Beschreibung von Capabilities,
    erweiterbaren Ergebnisformaten
    und Operationen

    → Nutzung von SRU/CQL und
    Erweiterungen nach SRU

  • Interface Spezifikation = Formate und Transportprotokoll

    • Endpoint = Brücke zwischen Client (FCS Formaten) und lokaler Suchmaschine

    • Client = Anwenderschnittstelle, Query-Eingabe und Ergebnispräsentation

  • Discovery und Search Mechanismus

FCS – Discovery

  • SRU Explain

    • Hilfe und Informationen für Client zu Zugriff, Anfrage und Verarbeitung von Ergebnissen vom Server

  • Informationen über Endpunkt

    • Capabilities: Basic Search, Advanced Search?

    • Ressourcen für Suche

    → Endpoint Description (XML) über explain SRU Operation

FCS – Endpoint Description

  • XML nach Schema Endpoint-Description.xsd

  • <ed:EndpointDescription>

    • @version mit “2”

    • <ed:Capabilities> (1)

    • <ed:SupportedDataViews> (1)

    • <ed:SupportedLayers> (1) (wenn Advanced Search Capability)

    • <ed:Resources> (1)

FCS – Endpoint Description (2)

  • <ed:Capability>

    • Inhalt: Capability Identifier, URI

      • http://clarin.eu/fcs/capability/basic-search

      • http://clarin.eu/fcs/capability/advanced-search

FCS – Endpoint Description (3)

  • <ed:SupportedDataView>

    • Inhalt: MIME-Typ, z.B. application/x-clarin-fcs-hits+xml

    • @id → Referenzierung in <ed:Resource>

    • @delivery-policy: send-by-default / need-to-request

    • keine Duplikate (nach MIME-Type) erlaubt

FCS – Endpoint Description (4)

  • <ed:SupportedLayer>

    • (nur bei Advanced Search)

    • Inhalt: Layer Identifier, z.B. “orth”

    • @id → Referenzierung in <ed:Resource>

    • @result-id → Referenzierung des Layers im Advanced Data View

    • @qualifier → Kennzeichner in FCS-QL Search Term für den Layer

    • @alt-value-info,[.blue]` @alt-value-info-uri`: kurze Beschreibung des Layer, z.B. für Tagset, + URL mit weiteren Informationen

    • keine Duplikate anhand @result-id MIME-Typ erlaubt

FCS – Endpoint Description (5)

  • <ed:Resource>

    • @pid: Persistent Identifier (z.B. MdSelfLink von CMDI Record)

    • <ed:Title> (1+) mit @xml:lang, keine Duplikate, English erforderlich

    • <ed:Description> (0+) mit @xml:lang, English erforderlich,

    • sollte maximal 1 Satz sein

    • <ed:LandingPageURI> (0/1) – Link zur Webseite der Ressource

    • <ed:Languages> (1) mit <ed:Language> mit Inhalt aus ISO 639-3

    • <ed:AvailableDataViews> (1) mit @ref = Liste von IDs der <ed:SupportedDataView> Elemente, z.B. “hits adv”

    • <ed:AvailableLayers> (1) (wenn Advanced Search Capability), mit @ref = Liste von IDs der <ed:SupportedLayer> Elemente, z.B. “word lemma pos”

    • <ed:Resources> (0/1) für Teil-Ressourcen

    • für <ed:AvailableDataViews> und <ed:AvailableLayers> sollten Unterressourcen dieselben Listen unterstützen, eine erneute Deklaration ist erforderlich

FCS – Endpoint Description (Examples)

Minimale Endpoint Description für BASIC Search
<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description" version="2">
  <ed:Capabilities>
    <ed:Capability>http://clarin.eu/fcs/capability/basic-search</ed:Capability>
  </ed:Capabilities>
  <ed:SupportedDataViews>
    <ed:SupportedDataView id="hits" delivery-policy="send-by-default">application/x-clarin-fcs-hits+xml</ed:SupportedDataView>
  </ed:SupportedDataViews>
  <ed:Resources>
    <!-- just one top-level resource at the Endpoint -->
    <ed:Resource pid="http://hdl.handle.net/4711/0815">
      <ed:Title xml:lang="de">Goethe Korpus</ed:Title>
      <ed:Title xml:lang="en">Goethe corpus</ed:Title>
      <ed:Description xml:lang="de">Das Goethe-Korpus des IDS Mannheim.</ed:Description>
      <ed:Description xml:lang="en">The Goethe corpus of IDS Mannheim.</ed:Description>
      <ed:LandingPageURI>http://repos.example.org/corpus1.html</ed:LandingPageURI>
      <ed:Languages>
        <ed:Language>deu</ed:Language>
      </ed:Languages>
      <ed:AvailableDataViews ref="hits" />
    </ed:Resource>
  </ed:Resources>
</ed:EndpointDescription>

FCS – Endpoint Description (Examples 2)

Endpoint Description mit CMDI Data View und Unter-Ressourcen
<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description" version="2">
  <ed:Capabilities>
    <ed:Capability>http://clarin.eu/fcs/capability/basic-search</ed:Capability>
  </ed:Capabilities>
  <ed:SupportedDataViews>
    <ed:SupportedDataView id="hits" delivery-policy="send-by-default">application/x-clarin-fcs-hits+xml</ed:SupportedDataView>
    <ed:SupportedDataView id="cmdi" delivery-policy="need-to-request">application/x-cmdi+xml</ed:SupportedDataView>
  </ed:SupportedDataViews>
  <ed:Resources>
    <!-- top-level resource 1 -->
    <ed:Resource pid="http://hdl.handle.net/4711/0815">
      <ed:Title xml:lang="de">Goethe Korpus</ed:Title>
      <ed:Title xml:lang="en">Goethe corpus</ed:Title>
      <ed:Description xml:lang="de">Das Goethe-Korpus des IDS Mannheim.</ed:Description>
      <ed:Description xml:lang="en">The Goethe corpus of IDS Mannheim.</ed:Description>
      <ed:LandingPageURI>http://repos.example.org/corpus1.html</ed:LandingPageURI>
      <ed:Languages>
        <ed:Language>deu</ed:Language>
      </ed:Languages>
      <ed:AvailableDataViews ref="hits" />
    </ed:Resource>
    <!-- top-level resource 2 -->
    <ed:Resource pid="http://hdl.handle.net/4711/0816">
      <ed:Title xml:lang="de">Zeitungskorpus des Mannheimer Morgen</ed:Title>
      <ed:Title xml:lang="en">Mannheimer Morgen newspaper corpus</ed:Title>
      <ed:LandingPageURI>http://repos.example.org/corpus2.html</ed:LandingPageURI>
      <ed:Languages>
        <ed:Language>deu</ed:Language>
      </ed:Languages>
      <ed:AvailableDataViews ref="hits cmdi" />
      <ed:Resources>
        <!-- sub-resource 1 of top-level resource 2 -->
        <ed:Resource pid="http://hdl.handle.net/4711/0816-1">
          <ed:Title xml:lang="de">Zeitungskorpus des Mannheimer Morgen (vor 1990)</ed:Title>
          <ed:Title xml:lang="en">Mannheimer Morgen newspaper corpus (before 1990)</ed:Title>
          <ed:LandingPageURI>http://repos.example.org/corpus2.html#sub1</ed:LandingPageURI>
          <ed:Languages>
            <ed:Language>deu</ed:Language>
          </ed:Languages>
          <ed:AvailableDataViews ref="hits cmdi" />
        </ed:Resource>
        <!-- sub-resource 2 of top-level resource 2 ... -->
      </ed:Resources>
    </ed:Resource>
  </ed:Resources>
</ed:EndpointDescription>

FCS – Endpoint Description (Examples 3)

Endpoint Description mit ADVANCED Search Capability Unterstützung
<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description" version="2">
  <ed:Capabilities>
    <ed:Capability>http://clarin.eu/fcs/capability/basic-search</ed:Capability>
    <ed:Capability>http://clarin.eu/fcs/capability/advanced-search</ed:Capability>
  </ed:Capabilities>
  <ed:SupportedDataViews>
    <ed:SupportedDataView id="hits" delivery-policy="send-by-default">application/x-clarin-fcs-hits+xml</ed:SupportedDataView>
    <ed:SupportedDataView id="adv" delivery-policy="send-by-default">application/x-clarin-fcs-adv+xml</ed:SupportedDataView>
  </ed:SupportedDataViews>
  <ed:SupportedLayers>
    <ed:SupportedLayer id="word" result-id="http://spraakbanken.gu.se/ns/fcs/layer/word">text</ed:SupportedLayer>
    <ed:SupportedLayer id="orth" result-id="http://endpoint.example.org/Layers/orth" type="empty">orth</ed:SupportedLayer>
    <ed:SupportedLayer id="lemma" result-id="http://spraakbanken.gu.se/ns/fcs/layer/lemma">lemma</ed:SupportedLayer>
    <ed:SupportedLayer id="pos" result-id="http://spraakbanken.gu.se/ns/fcs/layer/pos"
                       alt-value-info="SUC tagset"
                       alt-value-info-uri="https://spraakbanken.gu.se/parole/Docs/SUC2.0-manual.pdf"
                       qualifier="suc">pos</ed:SupportedLayer>
    <ed:SupportedLayer id="pos2" result-id="http://spraakbanken.gu.se/ns/fcs/layer/pos2"
                       alt-value-info="2nd tagset"
                       qualifier="t2">pos</ed:SupportedLayer>
  </ed:SupportedLayers>

  <ed:Resources>
    <!-- just one top-level resource at the Endpoint -->
    <ed:Resource pid="hdl:10794/suc">
      <ed:Title xml:lang="sv">SUC-korpusen</ed:Title>
      <ed:Title xml:lang="en">The SUC corpus</ed:Title>
      <ed:Description xml:lang="sv">Stockholm-Umeå-korpusen hos Språkbanken.</ed:Description>
      <ed:Description xml:lang="en">The Stockholm-Umeå corpus at Språkbanken.</ed:Description>
      <ed:LandingPageURI>https://spraakbanken.gu.se/resurser/suc</ed:LandingPageURI>
      <ed:Languages>
        <ed:Language>swe</ed:Language>
      </ed:Languages>
      <ed:AvailableDataViews ref="hits adv" />
      <ed:AvailableLayers ref="word lemma pos pos2" />
    </ed:Resource>
  </ed:Resources>
</ed:EndpointDescription>

FCS – Search

  • SRU SearchRetreive

  • Suche

    • Basic Search mit CQL

    • Advanced Search mit FCS-QL

  • Suchergebnisse werden im Resource (Fragment) und Data View Formaten serialisiert

  • Details bei Implementierung → Kapitel Resources und Data Views

FCS – SRU Extension Parameter

  • x-fcs-endpoint-description (explain)

    • “true” - <sru:extraResponseData> der Explain Antwort enthält das Endpoint Description Dokument

  • x-fcs-context (searchRetrieve)

    • Komma-separierte Liste von PIDs

    • Einschränkung der Suche auf Ressourcen mit diesen PIDs

  • x-fcs-dataviews (searchRetrieve)

    • Komma-separierte Liste von Data View Identifiern

    • Endpunkte sollten diese need-to-request Data Views mit ausliefern

  • x-fcs-rewrites-allowed (searchRetrieve)

    • “true” - Endpunkt kann Query vereinfachen für höheren Recall

FCS – Diagnostics

  • Ergänzungen zu den SRU Diagnostics → SRU 2.0 – Diagnostics

  • Präfix: http://clarin.eu/fcs/diagnostic/

  • Bezug auf die Extra-Request-Parameter

FCS – Diagnostics (Tabelle)

Identifier URIDescriptionImpact

http://clarin.eu/fcs/diagnostic/1

Persistent identifier passed by the Client for restricting the search is invalid.

non-fatal

http://clarin.eu/fcs/diagnostic/2

Resource set too large. Query context automatically adjusted.

non-fatal

http://clarin.eu/fcs/diagnostic/3

Resource set too large. Cannot perform Query.

fatal

http://clarin.eu/fcs/diagnostic/4

Requested Data View not valid for this resource.

non-fatal

http://clarin.eu/fcs/diagnostic/10

General query syntax error.

fatal

http://clarin.eu/fcs/diagnostic/11

Query too complex. Cannot perform Query.

fatal

http://clarin.eu/fcs/diagnostic/12

Query was rewritten.

non-fatal

http://clarin.eu/fcs/diagnostic/14

General processing hint.

non-fatal

Versionen und Rückwärtskompatibilität

  • “Clients MUST be compatible to CLARIN-FCS 1.0” (Quelle)

    • damit Implementierung von SRU 1.2

    • Beschränkung auf Basic Search Capability

    • Verarbeitung von Legacy XML Namespaces (SRU Response, Diagnostics)

  • Heuristik zur Versionserkennung (von Endpunkten)

    • Client: Explain-Request ohne version und operation Parameter

    • Endpoint: SRU Response <sru:explainResponse>/<sru:version>

  • Versionen

    • FCS 2.0 ↔ SRU 2.0

    • FCS 1.0 ↔ SRU 1.2 (SRU 1.1)

Hinweise zu FCS SRU Aggregator

  • momentan keine Unterstützung von nur FCS 2.0 Endpunkten

    • aus Kompatibilitätsgründen Support von Legacy FCS und FCS 1.0

    • Annahme, dass Endpunkte bei FCS 2.0 auch frühere FCS Versionen unterstützen… (mit CLARIN Bibliotheken kein Problem)

    → FCS 2.0 only Endpunkte erhalten somit trotzdem FCS 1.0 (SRU 1.2) Anfragen!

  • Aggregator sendet searchRetrieve-Anfragen mit nur jeweils einer Ressourcen-PID im x-fcs-context Parameter

    • d.h. Suchen über N Ressourcen eines Endpunktes → N separate Suchanfragen

Referenzimplementierungen

CLARIN Referenzbibliotheken (Java)

  • Entwicklung ab ~2012

  • Modularisiert: Client/Server, SRU/FCS, Parser

  • in Java 1.8+ (EOL: Ende 2030)

  • Umfangreiche Dokumentation, einzelne Tests (lange im Einsatz)

  • Artefakte im CLARIN Nexus, Code auf Github

  • Server/Endpunkt: externe Abhängigkeiten zu

    • Logging: slf4j

    • HTTP: javax.servlet:servlet-api

    • Parser: antlr4 (FCS-QL) / CQL

  • Build: maven

  • Deployment: jetty, tomcat, …

CLARIN Referenzbibliotheken (Python)

  • ~ 2022: Übersetzung Java-Referenzbibliotheken nach Python

  • Starke Orientierung an Java

    → (fast) gleiche Interfaces, Klassen-/Funktionsnamen

  • aber: leichte Optimierungen für Python, kein 1:1

  • Fokus (neue) FCS Endpunkte → keine Clienten!

  • Typisiert, Dokumentiert; auf PyPI veröffentlicht

  • Synchrones, minimales WSGI - erlaubt Einbettung in bestehende Apps

  • Python 3.8+

  • Abhängigkeiten zu

    • XML-Parse: lxml

    • HTTP/WSGI: werkzeug

    • Parser: PLY (CQL), ANTLR4 (FCS-QL)

CLARIN Referenzbibliotheken

  • Maven Endpoint Archetype: Java

  • FCS SRU Aggregator: Java

  • FCS Endpoint Tester: Java ← Test Konformität SRU/FCS Protokoll

  • Korp: Java, Python

Indexdata: CQL-Parser, Querela: Python Implementierungen

FCS Endpunkt – Aufbau und Struktur

  • Query Parser (CQL, FCS-QL)

  • FCS SRU Server

    • SRU Konfiguration, Versionen, Parameter, Diagnostics, Namespaces

    • XML SRU Writer

    • Request Parameter Parser, SRUServer (Request Handler)

    • Abstrakte SRU Interfaces (Ergebnisse, SRUSearchEngine)

    • Auth (Interface, WIP)

FCS Endpunkt – Aufbau und Struktur (Cont.)

  • FCS Simple Endpoint

    • FCS Konfiguration (Endpoint Description), Parameter, Diagnostics, Namespaces

    • XML Endpoint Description Parser, Record und DataView Writer

    • SimpleEndpointSearchEngineBase (SRUSearchEngine + FCS Ergänzungen)

  • FCS Endpoint für XYZ

    • Implementierung abstrakter Klassen und Anbindung an Suchmaschine, Query Übersetzung

    • Konfiguration: Endpoint Description, SRU Server Configuration

    • Deployment als Java Servlet Server oder WSGI-App

FCS Endpunkt – Initialisierung

SRUServerServlet / SRUServerApp (WebServer)

  • Default WebApp-Parameter setzen

  • Parsen der SRU Server Config

  • Erstellen der QueryParserRegistry (CQL)

  • Initialisieren der SRUSearchEngine

  • Erstellen von SRUServer (mit SearchEngine + Konfiguration)

SRUSearchEngine
(Nutzer-Implementierung, → SimpleEndpointSearchEngineBase)

  • Weitere Initialisierung der QueryParserRegistry (FCS-QL)

  • do_init (Nutzer-Init)

  • Erstellen der Endpoint Description

FCS Endpunkt – Kommunikationsfluss

[GET] Anfrage (eingehend)

↳ SRUServerServlet / SRUServerApp (WebServer)

↳ SRUServer

  • URL-Parameterauswertung

  • Multiplexing nach search/scan/explain

↳ SimpleEndpointSearchEngineBase (Nutzer-Implementierung)

  • Suchanfrage parsen (CQL/FCS-QL) and Suchmaschine senden

  • Ergebnis in SRUSearchResultSet verpacken

  • mögliche Diagnostics etc.

↲

  • mögliche Fehlerbehandlung

  • Generierung XML Output (SRU Parameter)

FCS Endpunkt – Klassenhierarchie

SRUServerServlet - java (Servlet) / SRUServerApp - python (WSGI)

Servlet Implementierung für Servlet Container, doGet-Handler, Setup von SRUServer
Wrapper/Anwendung, die vom Betreiber ausgeführt wird

SRUServer - java, python

SRU Protokoll Implementierung, handleRequest, Fehlerbehandlung, XML Output Generierung

SRURequestImpl - java, python

Konkrete SRU GET Parameterauswertung (Parsen, Validierung; SRU Versionen) + mögliche FCS-Parameter (“x-…​”), SRU-Versionsbestimmung

↳ SRURequest (Interface) - java, python

Dokumentation aller SRU Parameter

FCS Endpunkt – Klassenhierarchie (2)

XYZEndpointSearchEngine - korp: java, python

Konkrete Implementierung von createEndpointDescription, do*-Methoden

↳ SimpleEndpointSearchEngineBase (abstrakt) - java, python

Lifecyle (init → destroy), Integration von Endpoint Description, Interfaces für Nutzer

↳ SRUSearchEngineBase (abstrakt) - java

↳ SRUSearchEngine (Interface) - java, python

Interface: search, explain, scan

FCS Endpunkt – Klassenhierarchie (3)

XYZSRUSearchResultSet - korp: java, python

Konkrete Implementierung, nextRecord + writeRecord Iterator und Serialisierung von Ergebnissen

↳ SRUSearchResultSet (abstrakt) - java, python

Felder für searchRetrieve Operation Ergebnisse (total, records, …)

↳ SRUAbstractResult (Interface) - java, python

Diagnostics + ExtraResponseData

XYZSRUScanResultSet, XYZSRUExplainResult müssen nicht extra implementiert werden, default-Verhalten reicht hier

FCS Endpunkt – Klassenhierarchie (4)

SRUConstants - Java, Python

  • Diagnostic Codes

  • Namespaces

  • Python: SRU Parameter + Werte

SRUDiagnostic - Java, Python

  • Fehlerbehandlung, Message (Textbeschreibung) der Diagnostics

Endpunkt Konfigurationen

<?xml version="1.0" encoding="UTF-8"?>
<endpoint-config xmlns="http://www.clarin.eu/sru-server/1.0/">
    <databaseInfo>
        <title xml:lang="se">Språkbankens korpusar</title>
        <title xml:lang="en" primary="true">The Språkbanken corpora</title>
        <description xml:lang="se">Sök i Språkbankens korpusar.</description>
        <description xml:lang="en" primary="true">Search in the Språkbanken corpora.</description>
        <author xml:lang="en">Språkbanken (The Swedish Language Bank)</author>
        <author xml:lang="se" primary="true">Språkbanken</author>
    </databaseInfo>

    <indexInfo>
        <set name="fcs" identifier="http://clarin.eu/fcs/resource">
            <title xml:lang="se">Clarins innehållssökning</title>
            <title xml:lang="en" primary="true">CLARIN Content Search</title>
        </set>
        <index search="true" scan="false" sort="false">
            <title xml:lang="en" primary="true">Words</title>
            <map primary="true">
                <name set="fcs">words</name>
            </map>
        </index>
    </indexInfo>

    <schemaInfo>
        <schema identifier="http://clarin.eu/fcs/resource" name="fcs"
                sort="false" retrieve="true">
            <title xml:lang="en" primary="true">CLARIN Content Search</title>
        </schema>
    </schemaInfo>
</endpoint-config>

WebApp Parameter (web.xml o.Ä.) - Korp-Beispiel

  • SRU Version

  • SRU/FCS Stellschrauben

SRU (SRU Server Config) - Korp-Beispiel →

  • databaseInfo zu Endpunkt, aber keine Auswertung im Client?

  • default: indexInfo + schemaInfo

  • Pflicht: database Feld in serverInfo!

FCS (Endpoint Description) - Korp-Beispiel

  • FCS Version (1/2)

  • Capabilities, Layer, DataViews

  • Ressourcen

Resources und Data Views

Endpoint Description – Capabilities

http://clarin.eu/fcs/capability/basic-search

  • Erforderlich

  • Query: Volltextsuche (Basic) mit Minimal-CQL (AND/OR)

  • DataView: HITS

http://clarin.eu/fcs/capability/advanced-search

  • Optional

  • Query: FCS-QL (Strukturierte Suche über Annotationslayer)

  • DataView: HITS und Advanced

Endpoint Description – Capabilities (2)

  • Weitere Capabilities denkbar

    → aber auf Basic und Advanced beschränkt!

  • Bestimmen nicht nur Suchmodi!

  • In Arbeit:

    • Authentifizierung/Authorisierung

    • Lexikalische Suche: …/lex-search → LexCQL, LexHITS

    • Syntaktische Suche?

  • Hinweis: laut XSD besitzen Capability-URIs folgendes Schema http://clarin.eu/fcs/capability/\w([\.\-]{0,1}\w)*

BASIC Search

cat
"cat"
cat AND dog
"grumpy cat"
"grumpy cat" AND dog
"grumpy cat" OR "lazy dog"
cat AND (mouse OR "lazy dog")

  • Verpflichtend!

  • Einfache Volltextsuche

  • Contextual Query Language (CQL) als Anfragesprache

    • Endpunkte müssen “term-only” Queries unterstützen

    • können Boolean-Operatoren (AND/OR) und Sub-Queries unterstützen

    • bei Fehlern mit entsprechender Diagnostic abbrechen

    • Endpunkte entscheiden selber, worauf gesucht wird

      (Text, Normalisierung o.Ä.)

  • Ergebnisse serialisiert im Generic Hits (HITS) Data View

http://clarin.eu/fcs/capability/basic-search

ADVANCED Search

"walking"
[token = "walking"]
"Dog" /c
[word = "Dog" /c]
[pos = "NOUN"]
[pos != "NOUN"]
[lemma = "walk"]
"blaue|grüne" [pos = "NOUN"]
"dogs" []{3,} "cats" within s
[z:pos = "ADJ"]
[z:pos = "ADJ" & q:pos = "ADJ"]

  • Optional

  • Strukturierte Suche in annotierten Daten,

    repräsentiert in Annotationslayern

    → Anfragesprache FCS-QL

    • Anfragen können verschieden Annotationslayer verknüpfen

    • Endpunkte sollten möglichst so viele Annotationslayer unterstützen wie möglich

  • Ergebnisse serialisiert in Advanced (ADV) Data View und Generic Hits (HITS) Data View

http://clarin.eu/fcs/capability/advanced-search

FCS-QL

  • Annotationslayer, diese enthalten Annotationen eines Types (z.B. Text, POS-Tags, …)

  • Query erlaubt Kombination dieser Layer bei Anfrage

  • Jeder Layer ist segmentiert → Suche nach einzelnem Lemma

    • keine Vorgabe, wie Segmentierung stattfinden soll

    • Annahme, dass Segmentierung über Layer konsistent (für Darstellung im Advanced Data View)

FCS-QL – Hinweise

  • Endpunkte müssen FCS-QL komplett parsen können!

  • Anfragen mit nicht unterstützten Operatoren oder Layern?

    • Fehler mit Diagnostics erzeugen, oder

    • Umschreiben von Queries, wenn durch “x-fcs-rewrites-allowed” erlaubt

  • Suchen sind Case Sensitive (im Query konfigurierbar)

  • Suchen sollten auf Layern stattfinden, wo es Sinn macht,

    z.B. bei Vorhandensein mehrerer Text- oder POS-Layer

FCS-QL – Layertypen

Layer Type IdentifierAnnotation Layer DescriptionSyntaxExamples (without quotes)

text

Textual representation of resource, also the layer that is used in Basic Search

String

"Dog", "cat" "walking", "better"

lemma

Lemmatisation

String

"good", "walk", "dog"

pos

Part-of-Speech annotations

Universal POS tags

"NOUN", "VERB", "ADJ"

orth

Orthographic transcription of (mostly) spoken resources

String

"dug", "cat", "wolking"

norm

Orthographic normalization of (mostly) spoken resources

String

"dog", "cat", "walking", "best"

phonetic

Phonetic transcription

SAMPA

"'du:", "'vi:-d6 'ha:-b@n"

  • Universal Dependencies, Universal POS tags v2.0

  • Dafydd Gibbon, Inge Mertins, Roger Moore (Eds.): Handbook of Multimodal and Spoken Language Systems. Resources, Terminology and Product Evaluation, Kluwer Academic Publishers, Boston MA, 2000, ISBN 0-7923-7904-7

FCS-QL – Layer Type Identifier

  • identifiziert Layer für FCS-QL und Advanced Data View

  • Weitere Identifier sind nicht erlaubt, außer für Testzwecke

  • Custom Identifier müssen mit “x-” beginnen

Ergebnis-Serialisierung

  • Ergebnisse müssen im CLARIN FCS Format serialisiert werden

    • Resource (Fragment), Data View

    • XML → XSD

  • Wichtig: 1 Treffer = 1 Result Record

    • keine Kombination mehrerer Treffer in einem Record

      → für jeden Treffer eigene SRU Records generieren, die die selbe Ressource referenzieren

    • mehrere Hit-Marker sind erlaubt, z.B. bei Booleans um einzelne Terme zu highlighten

    • Jeder “Hit” (Treffer) sollte in einem Satzkontext definiert sein

Ergebnis-Serialisierung (Cont.)

Resource

  • “searchable and addressable entity” im Endpunkt, z.B. Textkorpus

  • eigenständige (“self contained”), d.h. ganzes Dokument, kein einzelner Satz aus einem Dokument

  • Adressierbar als Ganzes über Persistent Identifier oder unique URI

Resource Fragment

  • Teil einer Resource, z.B. einzelner Satz, oder Zeitintervall in Audio-Transkription (bei Multi-Modalen Korpora)

  • sollte adressierbar sein, innerhalb einer Resource (Offset / ID)

  • Nutzung optional, aber empfohlen

Data View

  • Serialisierung eines “Hits” (Treffers) in Resource (Fragment)

  • ermöglicht verschieden Darstellungen, erweiterbar

Ergebnis-Serialisierung – Linking

  • Endpunkte sollten Link zur Resource (Fragment) bereitstellen

    • persistent identifier (PID) / einzigartige URI

    • falls kein direktes Linking möglich, dann z.B. Webseite mit Beschreibung des Korpus / der Sammlung

    • Link sollte so spezifisch wie möglich sein

    • PIDs vor URIs, beides empfohlen

Ergebnis-Serialisierung – Beispiele

HITS Data View für eine Ressource mit PID
<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="http://hdl.handle.net/4711/00-15">
  <fcs:DataView type="application/x-clarin-fcs-hits+xml">
    <!-- data view payload omitted -->
  </fcs:DataView>
</fcs:Resource>
HITS Data View für eine Resource mit Resource Fragment für genauere Strukturierung
<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="http://hdl.handle.net/4711/08-15">
  <fcs:ResourceFragment>
    <fcs:DataView type="application/x-clarin-fcs-hits+xml">
      <!-- data view payload omitted -->
    </fcs:DataView>
  </fcs:ResourceFragment>
</fcs:Resource>

Ergebnis-Serialisierung – Beispiele (2)

Nutzung von CMDI Data View für Ressourcen-Metadaten neben HITS Ergebnis
<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource"
              pid="http://hdl.handle.net/4711/08-15"
              ref="http://repos.example.org/file/text_08_15.html">
  <fcs:DataView type="application/x-cmdi+xml" (1)
                pid="http://hdl.handle.net/4711/08-15-1"
                ref="http://repos.example.org/file/08_15_1.cmdi">
      <!-- data view payload omitted -->
  </fcs:DataView>

  <fcs:ResourceFragment pid="http://hdl.handle.net/4711/08-15-2" (2)
                        ref="http://repos.example.org/file/text_08_15.html#sentence2">
    <fcs:DataView type="application/x-clarin-fcs-hits+xml">
      <!-- data view payload omitted -->
    </fcs:DataView>
  </fcs:ResourceFragment>
</fcs:Resource>
1Angabe von CMDI-Metadaten zur Ressource
2Treffer ist Teil einer größeren Ressource “semantisch aussagekräftiger”

Data Views

  • Spezifikation (mit XSD-Schema, Beispielen)

  • Spezifiziert in FCS Core 2.0

    • Advanced (ADV) Data View

    • Generic Hits (HITS) Data View

  • Weitere Data Views wie Component Metadata (CMDI), Images (IMG), Geolocation (GEO) beschreiben, aber nicht im Standard Client “Aggregator” ausgewertet

Data Views (2)

  • Sende-Pflicht “send-by-default”

    oder Wunsch “need-to-request”

  • Generic Hits Data View ist Pflicht, muss immer gesendet werden

  • nur Data Views senden, die

    • mit (SRU) FCS Parameter “x-fcs-dataviews” angefordert, oder

    • Delivery-Policy “send-by-default” besitzen

  • ungültige Data Views → non-fatal Diagnostic für jede angefragte Data View

    http://clarin.eu/fcs/diagnostic/4

    ("Requested Data View not valid for this resource")

Hits Data View

Beschreibung

Representation eines Hits

MIME type

application/x-clarin-fcs-hits+xml

Payload Disposition

inline

Payload Delivery

send-by-default (REQUIRED)

Recommended Short Identifier

hits (RECOMMENDED)

XML Schema

DataView-Hits.xsd

  • Implementierungspflicht

  • Einfachste Serialisierung, (verlustbehaftete) Approximation von Ergebnissen

  • Jeder Treffer (Hit) sollte nur in einzelnen Satzkontext (o.Ä.) auftreten

  • Mehrere Hit-Annotationen möglich, z.B. bei Konjunktionen im Query

Hits Data View – Beispiele

HITS Data View mit einem Hit-Marker
<!-- potential @pid and @ref attributes omitted -->
<fcs:DataView type="application/x-clarin-fcs-hits+xml">
  <hits:Result xmlns:hits="http://clarin.eu/fcs/dataview/hits">
    The quick brown <hits:Hit>fox</hits:Hit> jumps over the lazy dog.
  </hits:Result>
</fcs:DataView>
HITS Data View mit mehreren Hit-Markern für Boolean-Queries
<!-- potential @pid and @ref attributes omitted -->
<fcs:DataView type="application/x-clarin-fcs-hits+xml">
  <hits:Result xmlns:hits="http://clarin.eu/fcs/dataview/hits">
    The quick brown <hits:Hit>fox</hits:Hit> jumps over the lazy <hits:Hit>dog</hits:Hit>.
  </hits:Result>
</fcs:DataView>

Kwic Data View

Beschreibung

Representation eines Hits

MIME type

application/x-clarin-fcs-kwic+xml

Payload Disposition

inline

Payload Delivery

send-by-default (REQUIRED)

Recommended Short Identifier

kwic (RECOMMENDED)

XML Schema

-

  • Deprecated!

  • Zur Kompatibilität mit Legacy FCS Clienten evtl.

  • Beispiel in CQP/SRU bridge

  • Abbildung von

    • linken und rechten Kontext

    • Treffer

  • Serialisierer Java, Python

  • Aggregator: Transformation zu Hits Data View!

Advanced Data View

Beschreibung

Representation eines Hits für die Advanced Search

MIME type

application/x-clarin-fcs-adv+xml

Payload Disposition

inline

Payload Delivery

send-by-default (REQUIRED)

Recommended Short Identifier

adv (RECOMMENDED)

XML Schema

DataView-Advanced.xsd

  • Serialisierung für die Advanced Search für multimediale Daten (Text, transkribiertes Audio)

  • Darstellung strukturierter Informationen über mehrere Annotationslayer

  • Annotationen sind Datenströme (Ranges) über dem Signal (Anfang + Ende)

  • Segmentierung über <Segment>, Annotationen in <Span> in <Layer>

    • Segmente müssen über alle Layer übereinstimmen

Advanced Data View – Beispiel

Advanced Data View - Stream Data

Advanced Data View – Beispiel (2)

Advanced Data View - Relation

Advanced Data View – Darstellung

Advanced Data View - Visualization in Aggregator

https://contentsearch.clarin.eu/?&queryType=fcs&query=%5B%20word%20%3D%20%22her.*%22%20%5D%20%5B%20lemma%20%3D%20%22Artznei%22%20%5D%20%5B%20pos%20%3D%20%22VERB%22%20%5D

Beispiele

→ siehe weitere Beispiele (searchRetrieve Query)
Endpunkt: https://spraakbanken.gu.se/ws/fcs/2.0/endpoint/korp/sru

Query Translation

Anfragesprachen

CQL-JS Demo

FCS-QL – Visualisierung

FCS-QL Parsebaum

  • Installation

    pip install antlr4-tools
git clone https://github.com/clarin-eric/fcs-ql.git
cd fcs-ql/src/main/antlr4/eu/clarin/sru/fcs/qlparser

  • Visualisierung nach ANTLR4 > Getting Started

    antlr4-parse src/fcsql/FCSParser.g4 src/fcsql/FCSLexer.g4 query -gui
[ word = "her.*" ] [ lemma = "Artznei" ] [ pos = "VERB" ]
^D

FCS-QL Query Nodes

QueryNode (mit Kind-Knoten “children”)

  • Expression (layer identifier, layer identifier qualifier, operator, regular expression + flags)

    • Wildcard

    • Group → 1 QueryNode; “(” … “)”

    • NOT → 1 QueryNode

    • AND, OR → Liste von QueryNodes

  • QueryDisjunction → Liste von QueryNodes

  • QuerySequence → Liste von QueryNodes → “Liste von QuerySegmenten”

  • QuerySegment (min, max) → Expression → “ein Token”

  • QueryGroup (min, max) → QueryNode

  • Within-Query (SimpleWithin, QueryWithWithin) (Scope: sentence, utterance, paragraph, turn, text, session) (ungenutzt)

FCS-QL Query Nodes – Aggregator

FCS-QL Query Builder

Geparster Query:

  • Query Sequence → mit Liste von Query Segment

    [ word = ".*her" ] [ lemma = "Artznei" ] [ pos = "VERB" ]

  • Query Segment → ein Token (kann sich wiederholen)

    [ word = "her.*" & ( word = "test" | word = "Apfel" ) ] [ pos = "ADV" ]{1,3}

    • Expression AND

      [ word = "her.*" & word = "test" ]

      • Expression Group

      • Expression

    • Expression Group → Expression OR → Liste von Expression

      [ ( word = "her.*" | word = "Test" ) ]

    • Expression → Layer Identifier, Operator, Regex (Wert)

      [ word = "her.*" ]

FCS-QL – Bemerkungen

  • aktuell (Aggregator v3.7.1) nur begrenzte Unterstützung von FCS-QL Features bei Anfrage

    → bedingt durch Visual Query Builder

  • zukünftig Freitext bzw. verbesserter Query Builder geplant

  • bei nicht-Unterstützung von Query Features entsprechende Diagnostics nutzen

    • SRU: \info:srw/diagnostic/1/48 - Query feature unsupported.

    • FCS: http://clarin.eu/fcs/diagnostic/10 - General query syntax error. - sollte durch FCS-QL Parser-Bibliothek abgefangen werden

    • FCS: http://clarin.eu/fcs/diagnostic/11 - Query too complex. Cannot perform Query.

Query-Mapping

  • Idee:

    • Raw Query (CQL, FCS-QL) von Bibliotheken lassen

    • Rekursiv durch den geparsten Query-Baum gehen, “depth first”

    • sukzessiv transformierten Query (für Zielsystem) generieren,

      z.B. StringBuilder in Java

  • Beispiele:

Query-Mapping (2)

  • ElasticSearch

  • Solr

    • nur BASIC Search

    • ADVANCED Search mit z.B. MTAS (“Multi Tier Annotation Search”)

  • Generell: für ADVANCED Search sollte konkrete Corpus Search Engine genutzt werden

    → oder es kann maximal ein Annotationslayer (“Text”) durchsucht werden

Endpunkt-Entwicklung

Visual Studio Code (Vorschlag)

CQL-JS Demo

Visual Studio Code – Debugging (Java)

  • für *.war/Jetty Web-Application Testing

  • kein Hot-Code Reloading / keine Änderungen zwischen Kompilierung und Debugging vornehmen!

  • VSCode Debug Setting:

    • Run and Debug > Add Configuration … > “Java: Attach by Process ID”

  • Mit Maven Anwendung ausführen:

    MAVEN_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -agentlib:jdwp=transport=dt_socket,server=y,address=5005" \
    mvn [jetty:run-war|...]

Visual Studio Code – Debugging (Python)

  • launch.json

    • pytest: im “Run and Debug” Menü keine vorgeschlagene Konfiguration

    • file/module: nach Gebrauch

  • settings.json

    • pytest: coverage muss hier deaktiviert werden!

{
    "name": "Python: pytest",
    "type": "python",
    "request": "launch",
    "console": "integratedTerminal",
    "purpose": [
        "debug-test"
    ],
    "justMyCode": false
}
"python.testing.pytestArgs": [
    ".",
    // disable coverage for debugging
    "--no-cov",
    // disable ansi color output (-vv)
    "-q",
],

Endpunkt Projekt Kickstart

CLARIN SRU/FCS Endpoint Archetype

  • Installation des Archetypes in lokales Maven Repository, oder

  • Konfiguration des CLARIN Nexus als Remote Repository

  • Projekt Generierung mit Maven:

mvn archetype:generate \
    -DarchetypeGroupId=eu.clarin.sru.fcs \
    -DarchetypeArtifactId=fcs-endpoint-archetype \
    -DarchetypeVersion=1.6.0 \
    -DgroupId=[ id.group.fcs ] \
    -DartifactId=[ my-cool-endpoint ] \
    -Dversion=[ 1.0-SNAPSHOT ] \
    -DinstitutionName=[ "My Institution" ]

  • alle […​ ] Platzhalter sind zu ersetzen mit den passenden Werten (bei Werten mit Leerzeichen mit Anführungszeichen umschließen)

  • wenn Archetype von Git installiert, dann archetypeVersion=1.6.0-SNAPSHOT nutzen (siehe Angabe in pom.xml)

Minimaler FCS Endpunkt

  • Notwendige Klassenimplementierungen

    • SimpleEndpointSearchEngineBase

    • SRUSearchResultSet

    • Wrapper oder Adapter für Suchmaschine (!)

  • Erforderliche Konfigurationen

    • sru-server-config.xml

    • endpoint-description.xml

    • WebApp-Konfigurationen

      (Java: web.xml, Python: Key-Value Parameter-Dict)

      • Verweis auf Implementierung der SimpleEndpointSearchEngineBase

      • Erforderliche SRU Parameter (host, port, server, …)

Minimaler FCS Endpunkt – Initialisierung

→ SimpleEndpointSearchEngineBase (Java, Python)

void doInit (ServletContext context, SRUServerConfig config, SRUQueryParserRegistry.Builder queryParsersBuilder, Map<String, String> params) - Java, Python

  • Erforderliche Implementierung!

  • (mögliche) Initialisierung von APIs, Default-Werten (PIDs), …

EndpointDescription createEndpointDescription (ServletContext context, SRUServerConfig config, Map<String, String> params) - Java, Python

  • Erforderliche Implementierung!

  • Laden der EndpointDescription (Java, Python)

    • eingebettete XML-Datei (mit dem SimpleEndpointDescriptionParser, Java, Python) oder

    • dynamische Konstruktion z.B. über API - Beispiel NoSketchEngine

Minimaler FCS Endpunkt – Scan/Explain

  • (theoretisch) nichts zu implementieren

    → Default-Handler für “explain” und “scan” beantworten Anfragen hier automatisch

  • Endpoint Description wird im Zweifel als “explain”-Operation ausgeliefert

→ SimpleEndpointSearchEngineBase (Java, Python)

Minimaler FCS Endpunkt – Suchanfrage

SRUSearchResultSet search (SRUServerConfig config, SRURequest request, SRUDiagnosticList diagnostics)

  • Parsen von Query (Suchanfrage)

    • Check von “queryType”-Parameter, ob CQL, FCS-QL, …

    • Fehler: SRU_CANNOT_PROCESS_QUERY_REASON_UNKNOWN

  • Auswerten von ExtraRequestData

    • “x-fcs-context” - angefragte Ressource

      • Diagnostic: FCS_DIAGNOSTIC_PERSISTENT_IDENTIFIER_INVALID - invalide PIDs

      • Fehler: SRU_UNSUPPORTED_PARAMETER_VALUE - z.B. zu viele PIDs, keine PIDs

    • “x-fcs-dataviews” - angefrage DataViews

      • Diagnostic: FCS_DIAGNOSTIC_PERSISTENT_IDENTIFIER_INVALID

  • Pagination → startRecord (1) / maximumRecords (-1)

  • Suche an lokale Suchmaschine

  • Wrappen von Ergebnissen in SRUSearchResultSet

  • “If in Doubt” → `SRU_GENERAL_SYSTEM_ERROR`

Anbindung Suchmaschine

  • Eingabe: Parameter von Suchanfrage

    • Query (übersetzt für Suchmaschine)

    • Ressource (PID)

    • Pagination: Offset + Anzahl, → startRecord (1) / maximumRecords (-1)

    • (Request-Objekt und Server Konfigurationen)

    • (alle globalen/statischen Objekte, wie API-Adapter usw.)

  • Ausgabe: Angaben für Antwort, Ergebnisse

    • Gesamtanzahl (optional, FCS 2.0 erlaubt Angabe zu Genauigkeit)

    • Liste von Ergebnissen

      • mit “Treffer-Highlighting” (Hits) (Basic + Advanced Search)

      • für FCS-QL (Advanced Search) tokenisiert (Begrenzungen durch Zeichenoffsets) mit optionalen Advanced Annotationslayern

    • Diagnostics

Anbindung Suchmaschine (2)

  • Wrapper für Ergebnisse

    • Gesamtzahl Ergebnisse

    • Liste von Ergebnissen (Text mit Hit-Offsets; Tokens + Annotationen)

    • Ressourcen-PID, Ergebnisdetail-URLs

  • SRUSearchResultSet-Implementierung

    • Iterator Interface → nextRecord(), writeRecord(); curRecordCursor

  • Bsp.: MyResults, NoSkESRUFCSSearchResultSet

protected NoSkESRUFCSSearchResultSet(..., MyResults results) {
    super(diagnostics);
    this.serverConfig = serverConfig;
    this.request = request;

    this.results = results;
    currentRecordCursor = -1;
    // ...

public int getTotalRecordCount() { return (int) results.getTotal(); }
public int getRecordCount() { return results.getResults().size(); }

public boolean nextRecord() throws SRUException {
    if (currentRecordCursor < (getRecordCount() - 1)) {
        currentRecordCursor++;
        return true; }
    return false; }

public void writeRecord(XMLStreamWriter writer) {
    MyResults.ResultEntry result = results.getResults().get(currentRecordCursor);

    XMLStreamWriterHelper.writeStartResource(writer, results.getPid(), null);
    XMLStreamWriterHelper.writeStartResourceFragment(writer, null, result.landingpage);
    // ...
    XMLStreamWriterHelper.writeEndResourceFragment(writer);
    XMLStreamWriterHelper.writeEndResource(writer);
}

Ergebnis-Serialisierung

  • SRUXMLStreamWriter - Java, Python

    • (intern), insbesondere für SRU “recordXmlEscaping”

  • XMLStreamWriterHelper - Java, Python (FCSRecordXMLStreamWriter)

    • Boilerplate + Hilfe zum Schreiben von Record, RecordFragment, Hits/Kwic DataView

  • AdvancedDataViewWriter - Java, Python

    • Hilfe beim Schreiben von Advanced Data Views

    • addSpans (Inhalt, Layer, Offset, Hit?)

      writeHitsDataView, writeAdvancedDataView

Minimale Konfiguration – Endpoint Description

  • FCS Version: 2

  • Capabilities: BASIC Search

  • Data Views: HITS

  • Resources: (min: 1)

    • Titel

    • Description

    • LandingPage URL

    • Languages → eine Sprache (ISO 639-3)

<?xml version="1.0" encoding="UTF-8"?>
<EndpointDescription xmlns="http://clarin.eu/fcs/endpoint-description"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://clarin.eu/fcs/endpoint-description ../../schema/Core_2/Endpoint-Description.xsd"
             version="2">
  <Capabilities>
    <Capability>http://clarin.eu/fcs/capability/basic-search</Capability>
  </Capabilities>
  <SupportedDataViews>
    <SupportedDataView id="hits" delivery-policy="send-by-default" >application/x-clarin-fcs-hits+xml</SupportedDataView>
  </SupportedDataViews>
  <Resources>
    <Resource pid="hdl:10794/sbkorpusar">
      <Title xml:lang="sv">Språkbankens korpusar</Title>
      <Title xml:lang="en">The Språkbanken corpora</Title>
      <Description xml:lang="sv">Korpusarna hos Språkbanken.</Description>
      <Description xml:lang="en">The corpora at Språkbanken.</Description>
      <LandingPageURI >https://spraakbanken.gu.se/resurser/corpus</LandingPageURI>
      <Languages>
        <Language>swe</Language>
      </Languages>
      <AvailableDataViews ref="hits"/>
    </Resource>
  </Resources>
</EndpointDescription>

Minimale Konfiguration – SRU

  • SRU Server Einstellungen → Endpunkt Konfigurationen (sru-server-config.xml)

    • databaseInfo mit generellen Infos zu Endpunkt

    • default: indexInfo + schemaInfo

    • notwendig: serverInfo > database (host und port by default)

  • Web Server Konfiguration

    • optionale Anpassung von SRU / FCS Parametern

    • Java: web.xml

    • Python: Key-Value Dictionary

Deployment FCS Endpoint (Java)

  • Nutzung von Maven (!) / pom.xml

    • <packaging>war</packaging>

    • Build Plugin:

      • org.apache.maven.plugins:maven-war-plugin[:2.6] (?)

      • org.apache.maven.plugins:maven-compiler-plugin

  • Erstellung von WAR-Artefakt

  • mvn clean compile war:war

  • mvn clean package (mit Tests usw.)

  • Ausführen mit Java Servlet Engine / HTTP Server wie Apache Tomcat / Eclipse Jetty / …

Deployment FCS Endpoint (Python)

Embedded FCS Endpoint (Python)

  • Test nur mit Python als WSGI-App in Flask

    → in kosh: PR, Commit

  • Idee:

    • SRUServer mit SRUSearchEngine (global) erstellen

    • nach Pfad gefilterte Anfragen an SRUServer leiten

def init(self, flask: Flask) -> None:
    self.server = self.build_fcs_server()
    flask.add_url_rule("some-path/fcs", "some-path/fcs", self.handle)

def build_fcs_server(self) -> SRUServer:
    params = self.build_fcs_server_params()
    config = self.build_fcs_server_config(params)
    qpr_builder = SRUQueryParserRegistry.Builder(True)
    search_engine = KoshFCSEndpointSearchEngine(
        endpoint_description=self.build_fcs_endpointdescription(),
        # ... other parameters
    )
    search_engine.init(config, qpr_builder, params)
    return SRUServer(config, qpr_builder.build(), search_engine)

def handle(self) -> Response:
    LOGGER.debug("request: %s", request)  # Flask/Werkzeug Request
    LOGGER.debug("request?args: %s", request.args)
    response = Response()                 # Flask/Werkzeug Response
    self.server.handle_request(request, response)
    return response

FCS Endpunkt – Erweiterbarkeit

  • Ermöglicht eigene Anfragesprachen, DataViews usw.

  • am Beispiel von LexFCS (FCS Erweiterung für Lexikalalische Ressourcen)

    → d.h. neue Query Language und DataView

  • LexCQL - Query Language (CQL Dialekt)

    • SRUQueryParser (java, python), analog zu CQLQueryParser (java, python)

      → LexCQLQueryParser mit LexCQLQuery

    • SimpleEndpointSearchEngineBase.doInit() (java, python)

      → queryParsersBuilder.register(new LexCQLQueryParser());

  • LexHITS - HITS Data View Erweiterung

    • im SRUSearchResultSet.writeRecord (java, python) entsprechende XML Ergebnis Serialisierung

Deployment

FCS Endpoint Tester

  • WebApp zum Testen der Konformität zur FCS Spezifikation von Endpunkten

  • Installation nutzt SNAPSHOT-Versionen der SRU/FCS Bibliotheken und normalerweise blockierte Funktionen zur Validierung der SRU/FCS Protokolle

FCS Endpoint Tester – Deployment

SRU/FCS SNAPSHOT Bibliotheken müssen direkt von Git installiert werden

$ git clone https://github.com/clarin-eric/fcs-sru-client.git && cd fcs-sru-client
$ mvn install
$ git clone https://github.com/clarin-eric/fcs-simple-client.git && cd fcs-simple-client
$ mvn install

Build mit Maven

$ git clone https://github.com/clarin-eric/fcs-endpoint-tester.git && cd fcs-endpoint-tester
$ mvn clean package

Deployment mit Jetty für http://localhost:8080/

$ JETTY_VERSION="9.4.51.v20230217"
$ wget https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-distribution/${JETTY_VERSION}/jetty-distribution-${JETTY_VERSION}.zip && unzip jetty-distribution-${JETTY_VERSION}.zip && rm jetty-distribution-${JETTY_VERSION}.zip
$ cd jetty-distribution-${JETTY_VERSION}/
$ java -jar start.jar --add-to-start=http,deploy
$ cd webapps/ && cp ../../target/FCSEndpointTester-X.Y.Z-SNAPSHOT.war ROOT.war && cd ..
$ java -jar start.jar

FCS Endpoint Tester – Deployment (Docker)

Docker Image erstellen

$ git clone https://github.com/clarin-eric/fcs-endpoint-tester.git && cd fcs-endpoint-tester
$ docker build -t fcs-endpoint-tester .

Container ausführen

$ docker run --rm -it -p 8080:8080 fcs-endpoint-tester

FCS SRU Aggregator

  • Primäre FCS Client-Anwendung

  • Zentrale Suchoberfläche für Benutzer,

    “aggregiert” FCS Suchanfragen an verteilte Endpunkte

FCS SRU Aggregator – Deployment

Anwendung bauen (nativ)

$ git clone https://github.com/clarin-eric/fcs-sru-aggregator.git && cd fcs-sru-aggregator
$ ./build.sh --jar

Konfiguration (Endpunkt Sideloading + Logging) in aggregator_devel.yml (aggregator.yml für Produktiv-Deployment)

  • aggregatorParams → additionalFCSEndpoints

  • logging → loggers

Ausführen für http://localhost:4019/

$ ./build.sh --run

FCS SRU Aggregator – Deployment (Docker)

Docker Image erstellen

$ git clone https://github.com/clarin-eric/fcs-sru-aggregator.git && cd fcs-sru-aggregator
$ docker build --tag=fcs-aggregator .

Docker Container ausführen

$ touch fcsAggregatorCorpora.json fcsAggregatorCorpora.backup.json
$ docker run -d --restart unless-stopped \
    -p 4019:4019 -p 5005:5005 \
    -v $(pwd)/aggregator.yml:/work/aggregator.yml:ro \
    -v $(pwd)/fcsAggregatorCorpora.json:/var/lib/aggregator/fcsAggregatorCorpora.json \
    -v $(pwd)/fcsAggregatorCorpora.backup.json:/var/lib/aggregator/fcsAggregatorCorpora.backup.json \
    fcs-aggregator

FCS Korp Endpoint

  • Referenz-Endpunkt für Korp

  • Beispiel → Korp-API öffentlich erreichbar, keine weitere Konfiguration erforderlich zum Testen

FCS Korp Endpoint – Deployment (Java)

Erstellen

$ git clone https://github.com/clarin-eric/fcs-korp-endpoint.git && cd fcs-korp-endpoint
$ mvn clean compile war:war

Deployment dann mit Jetty/Tomcat etc. analog zum FCS Endpoint Tester

FCS Korp Endpoint – Deployment (Python)

Deployment vorbereiten

$ git clone https://github.com/Querela/fcs-korp-endpoint-python.git && cd fcs-korp-endpoint-python
$ python3 -m venv venv && source venv/bin/activate
$ python3 -m pip install -e .

Test-Deployment (http://localhost:8080)

$ python3 -m korp_endpoint

Produktiv-Deployment mit Docker (http://localhost:5000)

$ docker build --progress=plain -t korpy .
$ docker run --rm -it -p 5000:5000 korpy

Deployment Hinweise

  • bei Nutzung von Docker und localhost müssen evtl. Netzwerkkonfigurationen angepasst werden, damit der Docker Container Zugriff auf den Host hat

    • → host.docker.internal

Ressourcen

Links

Publikationen

  • im Rahmen von Text+ → auf Zotero.org mit Tag “FCS”

  • Auflistung in Text+ Awesome FCS Liste

  • im Rahmen von CLARIN? → keine extra Bibliographie

    • CLARIN Federated Content Search (CLARIN-FCS) – Core Specification, 2014, Oliver Schonefeld et al.

    • Federated Search: Towards a Common Search Infrastructure, 2012, Herman Stehouwer et al.

    • mehrere Workshops