Die Dokumentation von Tabellen mit SQL

Die Dokumentation einer Tabelle soll ihr eine verständliche Bedeutung geben. Wir zeigen im folgenden, wie die Dokumentation einer Tabelle aufgebaut sein kann.

Es ist darauf zu achten, bei Änderungen an einer Datenbank, nötigenfalls auch die Dokumentation entsprechend anzupassen.

Angaben zur gesamten Datenbank

Erklärungen, die für alle Tabellen einer Datenbank gelten, werden nur einmal am Anfang des Skripts, das die Datenbank anlegt, festgehalten.

Hier können auch die Namen von Bearbeitern und Ansprechpartnern stehen.

Informationen, die schon dem Datenbankskript entnommen werden können müssen nicht in der Dokumentation wiederholt werden, falls diese sich an Leser richtet, die auch das Skript lesen und verstehen können.

Angaben zur gesamten Tabelle

Die Entitäten der Tabelle

Die meisten Tabellen beschreiben einen Art von Entitäten (Dingen). Es sollte angegeben werden, welche Art von Entitäten die Tabelle beschreibt.

Beschreibung des Entitätstyps: Diese Tabelle beschreibt natürliche Zahlen.

Die Zeilenaussageform (Zeilenform)

Wir hatten schon am Anfang des Kurses behandelt, daß eine Datenbank Aussagen enthält. Wir kommt man nun von Tabellen zu Aussagen ?

Die Zeilenaussageform (kurz: Aussageform , English “relvar predicate ” oder “relation predicate ”) ist der zentrale Teil der Dokumentation, denn erst sie gibt der Tabelle eine Bedeutung.

Die Aussageform ist eine Aussage, die Spaltennamen als Platzhalter enthält.

Aussageform für eine Zeile der Tabelle »Zahl«: „Die Zahl I hat die deutsche Bezeichnung DE und die englische Bezeichnung EN.“

Durch Einsetzen der Werte einer Zeile an der Stelle der Platzhalter, erhält man aus der Zeilenaussageform für jede Zeile eine Aussage (Zeilenaussage ).

Zeilen der Tabelle

+------+------+------+
| I    | DE   | EN   |
+------+------+------+
| 0    | Null | zero |
| 1    | Eins | one  |
| 2    | Zwei | two  |
+------+------+------+

Aussprachehinweis

zero ˈzɪroʊ

Zeilenaussagen für die Zeilen der Tabelle »Zahl«

„Die Zahl 0 hat die deutsche Bezeichnung ‚Null ‘ und die englische Bezeichnung ‘zero ’.“

„Die Zahl 1 hat die deutsche Bezeichnung ‚Eins ‘ und die englische Bezeichnung ‘one ’.“

„Die Zahl 2 hat die deutsche Bezeichnung ‚Zwei ‘ und die englische Bezeichnung ‘two ’.“

Die erhaltenen Aussagen bilden gemeinsam die Aussage der Tabelle (Tabellenaussage ). (Das heißt: Die Aussage der Tabelle ist die Konjunktion [Und-Verknüpfung] aller Zeilenaussagen der Tabelle.)

Falls die Zeilenaussageform nicht der Dokumentation entnommen werden kann, läßt sie sich oft mehr oder weniger gut (unter Einbeziehung aller vorhandenen Informationen) erraten. Dennoch ist es sicherer, es nicht darauf ankommen zu lassen, daß sie immer richtig erraten wird, und sie explizit anzugeben.

Die Phrasenform *

Manchmal soll eine Zeile keine Aussage, sondern nur eine Nominalphrase darstellen.

Beispielsweise muß eine Aussage zu einer Lieferung mit einem Verb immer eine Zeitform (wie in „Die Ware wurde geliefert.“, „Die Ware wird geliefert.“ oder „Die Waren wird geliefert werden.“) aufweisen.

Manchmal soll eine Zeile aber einfach nur eine Lieferung beschreiben, ohne daß dazu gesagt wird, ob diese in der Vergangenheit erfolgt, in der Gegenwart erfolgt oder in der Zukunft erfolgen wird oder nur möglicherweise erfolgen soll (Verbmodus Konjunktiv).

In solch einem Fall kann anstelle einer Aussageform auch eine Phrasenform verwendet werden, die zu einer Zeile eine Phrase angibt.

Im folgenden Beispiel sieht man eine Tabelle für Rechnungsposten zusammen mit einer Phrasenform.

Tabellenerzeugungsanweisung mit Phrasenform

CREATE TABLE POSTEN ( NAME VARCHAR ( 255 ), ANZAHL VARCHAR ( 255 ), WERT VARCHAR ( 255 ) );
-- "ANZAHL Artikel der Ware 'NAME' mit einem Wert von WERT Euro pro Stueck"

Durch Einsetzen der Werte einer Zeile für die Platzhalter mit den entsprechenden Namen wird dann aus der Phrasenform eine Nominalphrase.

Zeilenerzeugungsanweisung mit Phrase

INSERT INTO POSTEN ( NAME, ANZAHL, WERT ) VALUES ( 'Stuhl', '6', '720' );
-- "Sechs Artikel der Ware 'Stuhl' mit einem Wert von 720 Euro pro Stueck"

Eine Nominalphrase ist eine Zeichenfolge, die in einem Satz als Subjekt oder Objekt (im Sinne der Linguistik) verwendet werden könnte, beispielsweise „Karl“, „ein roter Tisch“ oder „das schnelle Auto, welches sich um seine Achse dreht“. Sie ist die sprachliche Darstellung einer Sache (einer Entität).'

Beispiel

Wir zeigen hier, wie die Dokumentation einer Tabelle aussehen kann, wenn sie als Kommentar in ein Skript über die Kommandos zum Anlegen der Tabelle geschrieben wird.

Dokumentation der Tabelle »ZAHL«

DROP SCHEMA S; CREATE SCHEMA S; USE S;
--   Tabelle "ZAHL"
--   Diese Tabelle beschreibt natürliche Zahlen.
--
--   Zeilenaussageform:
--     "Die Zahl I hat den deutschen Namen DE
--     und den englischen Namen EN."
--
CREATE TABLE ZAHL ( I VARCHAR ( 255 ), DE VARCHAR ( 255 ), EN VARCHAR ( 255 ) ); 
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '0', 'Null', 'zero' );
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '1', 'Eins', 'one'  );
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '2', 'Zwei', 'two'  );

Während jede Tabelle einer Datenbank in der Praxis dokumentiert sein sollte, werden Tabellen im weiteren Verlauf dieses Kurses nicht immer dokumentiert, da die Bedeutung einer Tabelle oft auch dem Text des Kurses entnommen werden kann und eine zusätzliche Dokumentation in Skripten diese durch die Vergrößerung der Skripte und der Lektionen diese unübersichtlicher machen kann.

Kurzdoku

Eine kurze Dokumentation kann wesentlich besser als gar keine Dokumentation und manchmal übersichtlicher als eine unnötig lange Dokumentation sein. Unter einer Kurzdoku verstehen wir hier einen Text, der zu jeder Tabelle nur die Zeilenaussageform angibt.

Kurzdoku: Tabelle »ZAHL«: Die Zahl »I« hat den deutschen Namen »DE« und den englischen Namen »EN«.

Die Vollständigkeit der Tabelle ⃗

Eine vollständige Tabelle beschreibt alle Entitäten ihres Entitätstyps. Dann kann man aus dem Fehlen einer Entität in der Tabelle folgern, daß es eine solche Entität nicht gibt.

Die Tabelle der Angestellten eines Unternehmens (etwa für Zwecke der Buchhaltung) ist normalerweise vollständig (sie muß für Buchhaltungszwecke ja immer vollständig sein). Das heißt, daß man aus dem Fehlen eines Namens in jener Tabelle schließen kann, daß es einen Angestellten mit jenem Namen nicht gibt.

Eine Tabelle von Büchern kann normalerweise nicht vollständig sein (falls die Art der Bücher nicht weiter eingeschränkt ist), da es unmöglich sein dürfte, alle jemals irgendwo erschienenen Bücher zu erfassen (oder genau zu definieren, wann etwas überhaupt als Buch gilt).

Angaben zur Aktualität ⃗

Falls die Informationen der Tabelle sich auf einen bestimmten Zeitpunkt beziehen, sollte angegeben werden für welchen Zeitpunkt die Daten gelten sollten.

Bei manchen Tabellen soll der Inhalt stets den aktuellen Stand wiedergeben. Dies ist nur dann möglich, wenn die Tabelle selber für den aktuellen Stand maßgeblich ist (beispielsweise, wenn jemand genau dann als Mitglied einer Gruppe gilt, wenn er in die Tabelle eingetragen wurde). Ansonsten kann eine Tabelle nicht immer aktuell sein, da es bei einer Veränderung der Welt normalerweise eine Weile braucht, bis die Tabelle aktualisiert werden kann (wenn die Tabelle Informationen über Erdbeben enthält, wird ein Erdbeben möglicherweise nicht immer sofort, wenn es sich ereignet, in die Tabelle eingetragen werden können, sondern erst mit einer gewissen Verzögerung). Damit der Benutzer die Aktualität der Tabelle abschätzen kann, sollte dann festgehalten werden, wie die Tabelle aktualisiert wird (beispielsweise „jeden Werktag werden alle Erdbebennachrichten erfaßt, die bis 12.00 mittags eingetroffen sind.“)

Details zu einzelnen Spalten ⃗

Erklärungen, die für alle Spalten einer Tabelle gelten oder die mehrere Spalten gemeinsam betreffen, sollten in der Dokumentation der Tabelle zu finden sein und nicht bei mehreren Spalten wiederholt werden. Allgemein sollten Wiederholungen umfangreicherer Erklärungen vermieden und nötigenfalls durch Verweise ersetzt werden.

Falls einige der folgenden Details für alle Spalten einer Tabelle gleich sind, kann es reichen, sie nur einmal für die gesamte Tabelle festzuhalten.

Identifikator oder Beschreibung? ⃗

Eine Zeile einer Tabelle enthält eine Beschreibung einer Entität. Dabei dienen einige Zellen vorwiegend der Identifikation der Entität (welche Entität wird beschrieben?) und andere Zellen enthalten dann Aussagen über die Entität (welche Eigenschaften hat die Entität?). Entsprechend kann man zu jeder Spalte angeben, ob sie ein Identifikator ist (also der Identifikation dient) oder eine Beschreibung ist (also der Information dient).

Bedeutung des Inhalts der Zellen dieser Spalte ⃗

Die Bedeutung der Werte dieser Spalte kann für die Spalte noch einmal ausführlicher und mit allen wichtigen Details beschrieben werden, obwohl das Wichtigste ja schon der Zeilenform entnommen werden kann.

Domänen der Spalten ⃗

Eine Domäne ergibt zu dem Wert einer Spalte eine Bedeutung. Damit erlaubt die Domäne eine genauere Unterscheidung als der Datentyp.

Beispielsweise könnten Personen und Bücher in jeweils einer Tabelle durchnumeriert gespeichert werden. Die Kennzahl einer Person und die Kennzahl eines Buches hat dann denselben Datentyp („Zahl“), aber es handelt sich um unterschiedliche Domänen, da Person #1 nicht gleich dem Buch #1 ist, daß beide Entitäten die gleiche Kennzahl haben, hat keine Bedeutung. Ein Vergleich der Zahlenwerte jener beiden Spalten ist nicht sinnvoll. Obwohl beide Zellen den Wert »1« enthalten, hat die »1« in der Spalte »Buch« eine andere Bedeutung als in der Spalte »Person«. In der Spalte »Buch« kennzeichnet die »1« das Buch 1, in der Spalte »Person« die Person »1«. Aber die Person 1 muß nicht in einer bestimmten Beziehung zum Buch 1 stehen, nur weil beide dieselbe Kennzahl haben

Bücher und Personen

Buch Person

Buch Titel Person Name

1 Anna Karenina 1 Miguel De Cervantes
2 Don Quixote 2 Daniel Defoe
3 Robinson Crusoe 3 Jane Austen
4 Emma 4 Leo Tolstoi

Jeder Spalte sollte eine Domäne so zugeordnet werden, daß zwei Spalten, bei denen Gleichheit der Werte einer Bedeutung hat, die gleiche Domäne haben, und Spalten, bei denen Gleichheit der Werte keine Bedeutung hat, unterschiedliche Domänen haben.

Für die Kennzahl einer Person kann beispielsweise die Domäne „Person“ festgelegt werden, für die Kennzahl eines Buches die Domäne „Buch“. Weitere Beispiele für Domänen wären: „Postleitzahl“, „Personenname“, „Temperatur“ oder „Höhe“. Man kann beispielsweise eine Postleitzahl mit einer anderen Postleitzahl vergleichen („Sind beide gleich?“), aber es hat normalerweise keinen Sinn eine Postleitzahl mit einer Temperatur zu vergleichen („Sind beide gleich?“).

Diese Domäne einer Spalte sollte in der Dokumentation angegeben werden.

Einmaligkeit der Werte ⃗

Es sollte zu jeder Spalte angegeben werden, ob derselbe Wert mehrfach in jener Spalte vorkommen darf. (Beispielsweise sollten zwei Entitäten nie dieselbe Kennzahl haben.)

Weitere Informationen ⃗

Weitere Arten von Informationen, die in der Dokumentation zu einer Spalten angegeben werden könnten:

Sind die Daten dieser Spalte zeitlich veränderlich?
Aus welche Quelle stammen die Daten?

Beispiel ⃗

Wir zeigen hier, wie die Dokumentation einer Tabelle aussehen kann, wenn sie als Kommentar in ein Skript über die Kommandos zum Anlegen der Tabelle geschrieben wird.

Dokumentation der Tabelle »ZAHL«

--   Tabelle "ZAHL"
--   Diese Tabelle beschreibt natürliche Zahlen.
--
--   Zeilenaussageform:
--     "Die Zahl I hat den deutschen Namen DE
--     und den englischen Namen EN."
--
--   Vollstaendig?
--     Nein
--
--   Stand
--     2033-08-11
--
--   Identifikator "I":
--     Die Schreibweise einer Zahl im Zehnersystem.
--     Domaene: eine natuerliche Zahl
--     Einmalige Werte: Ja
--
--   Beschreibung "DE":
--     ein deutscher Name dieser Zahl.
--     Domaene: ein deutsches Substantiv fuer eine Zahl
--     Einmalige Werte: Ja
--
--   Beschreibung "EN":
--     ein englischer Name dieser Zahl.
--     Domaene: ein englisches Substantiv fuer eine Zahl
--     Einmalige Werte: Ja
DROP SCHEMA S; CREATE SCHEMA S; USE S;
CREATE TABLE ZAHL ( I VARCHAR ( 255 ), DE VARCHAR ( 255 ), EN VARCHAR ( 255 ) ); 
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '0', 'Null', 'zero' );
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '1', 'Eins', 'one'  );
INSERT INTO ZAHL ( I, DE, EN ) VALUES ( '2', 'Zwei', 'two'  );