An dieser Stelle entsteht die öffentliche Dokumentation für Epigraf 5. Diese Seite ist noch in Bearbeitung.
Mit der Importfunktion von Epigraf können CSV-Dateien und XML-Dateien in die Datenbanken eingespielt werden - darüber lassen sich sowohl neue Artikel, Abschnitte und Kategorien anlegen als auch bestehende Datensätze aktualisieren. Im Footer der Seiten befindet sich ein Import-Button, über den diese Dateien hochgeladen werden. Alternativ kann die API für den Import verwendet werden - dafür werden aktuell ein R-Package und ein Python-Package entwickelt. Für den Import müssen die entsprechenden Rechte freigegeben werden.
Das Relational Article Model (RAM)
Epigraf implementiert das Relational Article Model (RAM), mit dem Dokumente in Tabellen für Projekte, Artikel, Abschnitte, Inhalte, Annotationen und Kategorien erfasst werden. Vor dem Importieren muss deshalb überlegt werden, wie die vorhandenen Daten im Relational Article Model abgebildet werden sollen, das heißt welche Daten in welche Felder einer Tabelle überführt werden sollen. Dazu ist ein grundlegendes Verständnis des Datenmodells hilfreich.
Die Verknüpfung der Daten erfolgt beim Importieren in der Regel über IRIs. Das sind weltweit eindeutige Identifikatoren - jeder Datensatz verfügt in Epigraf über eine IRI. Vor diesem Hintergrund wird eine Importtabelle aufgebaut. Sollen beispielsweise Kategorien importiert werden, kann die Importtabelle wie folgt strukturiert sein:
| id | lemma |
|---|---|
| properties/categories/scifi | Science Fiction |
| properties/categories/musical | Musical |
| properties/categories/drama | Drama |
Die ID ist in diesem Fall ein IRI-Pfad. Sie setzt sich aus der Zieltabelle properties, dem Kategorientyp categories und einem eindeutigen IRI-Fragment für den Datensatz zusammen. Welche Typen innerhalb einer Tabelle zur Verfügung stehen, wird über die Epigraf-Konfiguration spezifisch für das Domänenmodell festgelegt. Der hier verwendete Typ bezieht sich auf die movies-Beispieldatenbank. Das IRI-Fragment kann nahezu beliebig gebildet werden und aus Zahlen oder Buchstaben bestehen.
Die Verwendung von IRI-Pfaden stellt erstens sicher, dass beim wiederholten Importieren der gleichen Daten keine neuen Datensätze angelegt werden. Stattdessen wird beim Importieren abgeglichen, ob bereits zugehörige Datensätze vorhanden sind. In diesem Fall werden sie überschrieben. Sie werden nur neu angelegt, wenn noch kein Datensatz mit dem IRI-Fragment vorhanden ist.
Über die IRI-Pfade wird zweitens die Verknüfung zwischen den Datensätzen hergestellt. Soll beispielsweise Text in einen Artikel importiert werden, kann eine Importtabelle wie folgt strukturiert sein:
| id | name | content | projects_id | articles_id | sections_id |
|---|---|---|---|---|---|
| projects/default/movies | Movies | ||||
| articles/default/0001 | Chronicles of Narnia | projects/default/movies | |||
| sections/text/0001 | Abstract | projects/default/movies | articles/default/0001 | ||
| items/text/0001 | The Chronicles of Narnia is a series of films based on the novels by C.S. Lewis. | projects/default/movies | articles/default/0001 | sections/text/0001 |
Im Beispiel wird in der letzten Zeile ein Itemdatensatz mit der Beschreibung eines Films angelegt. Die Beschreibung landet in einem Item vom Typ text mit dem IRI-Fragment 0001. Dieses Item wird in den Abschnitt mit dem IRI-Pfad sections/text/0001 eingefügt, der wiederum im Artikel mit dem IRI-Pfad articles/default/0001 angelegt wird.
Entsprechende Importtabellen können direkt als CSV-Dateien importiert werden. Auch das XML-Format orientiert sich daran und bildet die Tabellenstruktur ab. Die Packages für den Import per API unterstützen beim Umwandeln von Daten in das Zielformat und laden Importtabellen mit einem Befehl direkt aus R- oder Python-Skripten hoch.
Welche Felder stehen zur Verfügung?
Grundsätzlich stehen für den Import alle Felder zur Verfügung, die beim Export eines Datensatzes enthalten sind bzw. die in der Entwicklungsdokumentation dokumentiert sind. Alle Zieltabellen teilen sich beim Importieren die Felder, zum Beispiel für den Namen eines Artikels und den Namen eines Abschnitts. Für einen Datensatz irrelevante Felder - bei Artikeln etwa das Feld content - bleiben leer.
Für einige Felder können alternative Spalten verwendet werden, um die Datei übersichtlicher zu halten:
- In den jeweiligen Tabellen kann das Feld
typeanstelle von projecttype, articletype, sectiontype, itemtype, propertytype, usertype, scope oder from_tagname verwendet werden. - In der items-Tabelle kann das Feld
to_idanstelle von links_tab und links_id verwendet werden, idealerweise enthält es einen IRI-Pfad. - In der links- und der footnotes Tabelle reicht das Feld
root_idanstelle von root_tab und root_id, sofern daraus die Tabelle hervorgeht. Idealerweise wird ein IRI-Pfad verwendet. Gleiches gilt fürfrom_idundto_id.
Projekte
| Name | Erläuterung | Feld im Datenmodell | Beispiel |
|---|---|---|---|
| id | IRI-Pfad | ||
| published | |||
| type | IRI-Type | projecttype | |
| iri | IRI-Fragment | norm_iri | |
| sortno | Sortiernummer (Zahl) | ||
| signature | Kurztitel (Text) | ||
| name | Langtitel (Text) | ||
| content | Beschreibung (JSON) | ||
| norm_data | Normdaten (Text) |
Artikel
| Name | Erläuterung | Feld im Datenmodell | Beispiel |
|---|---|---|---|
| id | IRI-Pfad | ||
| published | |||
| type | IRI-Typ | articletype | |
| iri | IRI-Fragment | norm_iri | |
| sortno | Sortiernummer (Zahl) | ||
| signature | Identifikator (Text) | ||
| name | Titel (Text) | ||
| status | Status (Text) | ||
| norm_data | Normdaten (Text) | ||
| creator | Autor (IRI-Pfad) | created_by | |
| modifier | Bearbeiter (IRI-Pfad) | modified_by | |
| project | Projekt (IRI-Pfad) | projects_id |
Abschnitte
| Name | Erläuterung | Feld im Datenmodell | Beispiel |
|---|---|---|---|
| id | IRI-Pfad | ||
| published | |||
| type | IRI-Typ | sectiontype | |
| iri | IRI-Fragment | norm_iri | |
| sortno | Sortiernummer (Zahl) | ||
| number | Nummer (Zahl) | ||
| name | Bezeichnung (Text) | ||
| signature | Alternative Bezeichnung (Text) | alias | |
| content | Notiz (Text) | comment | |
| layout_cols | Anzahl der Spalten eines Gitters (Zahl) | ||
| layout_rows | Anzahl Zeilen eines Gitters (Zahl) | ||
| articles_id | Artikel (IRI-Pfad) | ||
| parent_id | ÜBergeordneter Abschnitt (IRI-Pfad) |
Inhalte
| Name | Erläuterung | Feld im Datenmodell | Beispiel |
|---|---|---|---|
| id | IRI-Pfad | ||
| published | |||
| type | IRI-Typ | itemtype | |
| iri | IRI-Fragment | norm_iri | |
| sortno | Sortiernummer (Zahl) | ||
| value | Einzelner Wert (Text) | ||
| content | Inhalt (Text) | ||
| translation | Übersetzung (Text) | ||
| property | Kategorie (IRI-Pfad) | properties_id | |
| pos_x | Position im Gitter (Zahl) | ||
| pos_y | Position im Gitter (Zahl) | ||
| pos_z | Position im Gitter (Zahl) | ||
| sections_id | Abschnitt (IRI-Pfad) | ||
| articles_id | Artikel (IRI-Pfad) |
To be added: to_id, flagged, file_*, date_*, source_*
Typen
| Name | Erläuterung | Feld im Datenmodell | Beispiel |
|---|---|---|---|
| id | IRI-Pfad | ||
| type | IRI-Typ | scope | |
| iri | IRI-Fragment | norm_iri | |
| sortno | Sortiernummer (Zahl) | ||
| name | Name (Text) | ||
| caption | Beschriftung (Text) | ||
| mode | Modus (Text) | ||
| category | Kategorie (Text) | ||
| description | Beschreibung (Text) | ||
| config | Konfiguration (JSON) |
Wie werden Datensätze miteinander verbunden?
Projekte enthalten Artikel, Artikel bestehen aus Abschnitten und Abschnitte umfassen Einträge. In den Einträgen wiederum wird auf Kategorien verwiesen. Die Verbindung zwischen all diesen Datensätzen erfolgt beim Importieren über die IDs. Für einen Abschnitt wird im Beispiel nicht nur eine eigene ID angegeben, sondern auch die ID des zugehörigen Artikels, gleiches gilt für den Item-Datensatz:
| id | articles_id | sections_id | name | content |
|---|---|---|---|---|
| articles-tmp1 | Ein Artikel | |||
| sections-tmp1 | articles-tmp1 | Ein Abschnitt | Kommentar zum Abschnitt | |
| items-tmp1 | articles-tmp1 | sections-tmp1 | Der Inhalt des Abschnitts |
Die IDs können auf drei verschiedene Arten gebildet werden:
- IRI-Pfade (Internationalized Resource Identifiers) sind besonders flexibel und empfehlenswert, da sie auch ohne Kenntnis datenbankinterner IDs den Datentransfer zwischen unterschiedlichen Datenbanken erlauben. Sie werden nach dem Schema
<table>/<type>/<irifragment>gebildet. Beispiel:properties/languages/iso-de-de. - Temporäre IDs werden nicht in die Datenbank importiert, sondern nur für die Verknüpfung innerhalb einer CSV-Datei verwendet. Sie werden nach dem Schema
<tabelle>-tmp<id>gebildet, das heißt auf die Angabe der Tabelle folgt nach einem Trennstrich das Präfix "tmp" und dann die Angabe einer Bezeichnung, die aus beliebigen Buchstaben und Zahlen zusammengesetzt sein kann. Beim Importieren werden automatisch datenbankspezifsche IDs angelegt und alle Datensätze korrekt verknüpft. Beispiel:articles-tmp123. - Datenbank-IDs müssen einem vorhandenen Datensatz entsprechen. Sie werden verwendet, um bestehende Daten zu überschreiben oder auf bestehende Daten zu verweisen. Diese IDs werden nach dem Schema
<tabelle>-<id>gebildet, wobei der Platzhaltter<id>eine vorhandene numerische ID enthält. Beispiel:articles-1.
Inwiefern die IDs in einer Importdatei korrekt aufgelöst werden können, lässt sich in der Import-Vorschau kontrollieren. Alle in der Datenbank bestehenden Datensätze sind grün markiert.
Wie werden Datensätze aktualisiert statt neu angelegt?
Werden IRIs oder Datenbank-IDs verwendet (siehe oben) und ein Datensatz ist bereits vorhanden, dann wird er nicht neu angelegt, sondern überschrieben. Zur Angabe der IRIs kommen zwei Varianten in Frage:
- Ein vollständiger IRI-Pfad wird in der
id-Spalte angegeben, zum Beispiel "properties/languages/iso-de-de". - Die Komponenten des IRI-Pfads werden in den jeweiligen Spalten angegeben. Der Tabellenname "properties" ergibt sich aus der
table-Spalte (oder aus der temporären ID). Zusätzlich ist die Angabe des Datensatztyps "languages" in dertypes-Spalte erforderlich, damit automatisch der IRI-Pfad gebildet werden kann. Das IRI-Fragment wird in deriri-Spalte angegeben, etwa "iso-de-de".
Das weitere Verhalten kann bei Bedarf über die Spalten _action und _fields gesteuert werden:
- _action=clear: Untergeordnete Datensätze werden gelöscht, um Platz für die folgenden Datensätze zu schaffen. So kann beispielsweise ein Abschnitt geleert werden, bevor in den folgenden Zeilen neue Einträge importiert werden.
- _action=skip: Der Datensatz wird nicht importiert, also auch nicht überschrieben. Der Datensatz ist lediglich dazu da, Verknüpfungen zu ermöglichen. Dazu können im Datensatz eine temporäre ID (auf die andere Zeilen verweisen) und die dazugehörigen Komponenten des IRI-Pfades (der zu einer Datenbank-ID aufgelöst wird) angegeben werden. Einfacher ist in der Regel aber die Verwendung von IRI-Pfaden.
- _fields: Alle Tabellen in einer Importdatei teilen sich die Spalten. Etwa werden der Kommentar eines Abschnitts ebenso wie der Text eines Eintrag in der Spalte
contentangegeben. Ist das Feld leer, wird es geleert. Mit einer Angabe in der_fields-Spalte wird alternativ festgelegt, dass nur die angegebenen Spalten berücksichtigt werden, um beispielsweise den Kommentar eines Abschnitts nicht zu überschreiben, aber den Inhalt eines Eintrags. Es müssen dazu mit einem Komma getrennt alle Felder aufgelistet werden, die zu berücksichtigen sind (Achtung: die ID-Felder nicht vergessen). Fehlt die_fields-Spalte oder ist sie leer, werden alle Felder berücksichtigt.