Von typisierten zu typenlosen APIs

By
Adrien Grand

In Version 5.0 haben wir begonnen, die Voraussetzungen für ein Ende der Typen in Elasticsearch zu schaffen. Mit Version 7.0 gehören Typen nun der Vergangenheit an. Typen waren darauf ausgelegt, mehrere Mandanten innerhalb eines einzelnen Index bereitzustellen. Dies ist jedoch nicht mit Lucene kompatibel. Leider verursachten Typen häufig mehr Probleme als sie lösten. Nach langen Diskussionen darüber, ob wir dieses Problem umgehen sollten (z. B. durch Verwendung einzigartiger Felder pro Typ oder eines Index pro Typ), entschlossen wir uns, stattdessen Typen nicht mehr zu unterstützen. Wir führten die Änderungen schrittweise über vier Hauptversionen ein, um unseren Anwendern die Umstellung zu erleichtern:

  • Ab Version 5.0 müssen Felder, die den gleichen Namen für mehrere Typen verwenden, kompatible Mappings aufweisen.
  • Ab Version 6.0 wird verhindert, dass Indizes mehr als einen Typ aufweisen. Zudem gilt das Mapping _default_ ab dieser Version als veraltet.
  • Ab Version 7.0 gelten typisierte APIs als veraltet. Stattdessen wurden neue typenlose APIs eingeführt und das Mapping _default_ wird nicht mehr unterstützt.
  • In Version 8.0 werden APIs, die Typen unterstützen, entfernt.

Typenlose APIs

Alle APIs, die Typen im URL-Pfad, Anforderungstext oder Antworttext akzeptieren, erhalten eine neue typenlose Entsprechung. Dies ist für einige gängige APIs der Fall, wie z. B. „index creation“, „index“ und „GET“. Das folgende Beispiel veranschaulicht eine Interaktion mit einem Cluster der Version 7.0 mit typenlosen APIs: 

PUT index
{
  "mappings": {
    "properties": { // Note how there is no top-level key with the type name
      "@timestamp": {
        "type": "date"
      }
    }
  }
}
PUT index/_doc/1 // _doc becomes the new endpoint for document index, get and delete requests
{
  "@timestamp": "2019-02-20"
}
POST index/_bulk
{"index": {"_id": "2"}} // no _type in the URL or in document metadata
{"@timestamp": "2019-03-01"}
{"update": {"_id": "1"}}
{"@timestamp": "2019-02-21"}
GET index/_doc/2
GET index/_search // unchanged, the `GET index/{type}/_search` endpoint is deprecated however
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "2019-01-01"
      }
    }
  }
}
GET index/_explain/1 // note how the type does not appear in the URL anymore, this would have been "GET index/{type}/1/_explain" in 6.x
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "2019-01-01"
      }
    }
  }
}

Erforderliche Vorgehensweise

Einige Änderungen sind so grundlegend, dass Sie Ihr Cluster vor dem Upgrade auf Version 7.0 entsprechend bearbeiten müssen. Andere Änderungen sind erst für das Upgrade auf Version 8.0 erforderlich und sollten nach dem Upgrade auf Version 7.0 durchgeführt werden.

Vor dem Upgrade

Version 6.8 muss installiert sein

Falls Sie ein schrittweises Upgrade ohne Ausfallzeit planen, sollten Sie zunächst ein Upgrade auf Version 6.8 durchführen. Dies ist das einzige Release der Version 6.x, das einige für das reibungslose Upgrade auf Version 7.0 erforderliche Funktionen enthält, wie beispielsweise die Unterstützung des Parameters include_type_name.

Vermeiden Sie das Mapping „_default_“

Die Unterstützung des Mappings _default_ wird ab Version 7.0 schrittweise eingestellt. Die Verwendung des Mappings _default_ in einigen vorhandenen Indizes der Version 6.x stellt kein Problem dar, da das Mapping _default_ lediglich für neue Indizes abgelehnt wird.

Aktualisieren Sie Ihre Indexvorlagen und Ihren Anwendungscode, um diese Mappings dem eigentlichen Typ hinzuzufügen, statt sie in das Mapping _default_ zu integrieren. Wenn der Name des Typs nicht wirklich wichtig für Sie ist, sollten Sie _doc verwenden. Dies erleichtert Ihnen in Zukunft den Übergang zu typenlosen APIs.

Übergeben Sie include_type_name=true an die APIs „index creation“, „template“ und „mappings“

Der Wechsel zu typenlosen APIs bedeutet, dass APIs, für deren Anforderungstext ein Typ erforderlich ist, nun ein anderes Format erwarten:

  • create index
  • put mapping
  • put template

Andere APIs, bei denen Typen in der Antwort zurückgegeben wurden, weisen hingegen nun ein anderes Antwortformat auf:

  • get index
  • get mapping
  • get field mapping
  • get template

Damit Sie diese Änderungen unbeschadet überstehen, sollten Sie dafür sorgen, dass Ihre Anwendung include_type_name=true an diese API-Aufrufe übergibt. Dies ist eine No-op in Version 6.x und weist Version 7.x an, das Verhalten dieser APIs so zu gestalten, wie dies in Version 6.x der Fall war. Das folgende Beispiel zeigt einen Aufruf zur Indexerstellung mit diesen Parametern. Die Funktionsweise ist in Version 6.8 und Version 7.x identisch. 

PUT index?include_type_name=true
{
  "mappings": {
    "my_type": {
      "properties": { // Note how there is no top-level key with the type name
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

Nach dem Upgrade

Wenn Sie vor dem Upgrade die empfohlenen Schritte ausgeführt haben, sollte alles weiterhin reibungslos funktionieren. In dieser Phase verwenden Sie jedoch immer noch APIs, die Typen akzeptieren, und dies löst Warnungen zu veraltetem Code aus. Migrieren Sie zu typenlosen APIs, um diese Warnungen zu vermeiden.

Für die APIs „index creation“, „template“ und „mappings“ müssen Sie include_type_name=true aus den URL-Parametern entfernen und den Anforderungstext oder die Erwartungen hinsichtlich des Antwortformats, das keine Typen mehr enthält, ändern. Falls der Anforderungstext oder die Antwort Mappings enthielt, sah einer der Abschnitte in der Regel wie folgt aus: 

{
  "my_type": { // this key is no longer accepted in mappings as of 7.0
    "properties": ...
  }
}

Der Typname muss hier entfernt werden. Die aktualisierte Version würde wie folgt aussehen: 

{
  "properties": ...
}

Für andere APIs wie „index“, „GET“ oder „update“ muss der Typname in der URL durch _doc ersetzt werden. Dies funktioniert unabhängig vom Namen des Typs in Ihrem Index. Falls Sie beispielsweise zuvor Indexaufrufe für einen Index mit dem Typnamen my_type durchgeführt haben, hätte der Indexaufruf wie folgt ausgesehen: 

PUT index/my_type/1
{
  "@timestamp": "2019-02-20"
}

Dieser Indexaufruf sollte nun wie folgt ersetzt werden: 

PUT index/_doc/1
{
  "@timestamp": "2019-02-20"
}

Weitere Informationen

Wenn Sie mehr über das Entfernen von Typen und die Vorgehensweise zur Migration zu typenlosen APIs erfahren möchten, schauen Sie sich unsere Dokumentation zum Entfernen von Typen an, in der wir die Auswirkungen dieser Änderungen und die Vorbereitungen für diese Änderungen ausführlicher erläutern.

Laden Sie Version 7.0.0 herunter, probieren Sie diese neuen typenlosen APIs aus und geben Sie uns dann auf Discuss Feedback hierzu.