About This Document

This document describes the SokweDB data management system, it’s features and capabilities. This includes the system design principals, a description of the database’s tables, and the intended usage of related programs. It does not describe the procedures used to enter data into the system or extract data from it. Nor does it describe the details of how to operate all related programs, or maintain the underlying software.

Conventions

In other words, this document describes the system’s capabilities. How to use the system on a day-to-day basis, which features are used in which ways, and similar, are to be found elsewhere.[1]

This section describes the conventions used within this document, which also speaks to the conventions of the overall database design.

There are a number of conventions regarding character case. The database is case insensitive when it comes to the names used to identify content – table names and column names and so forth.[2] Within this document schema names are written with an initial capital letter, table and view names are written in all upper case, and column names are written with initial capital letters.

Unless otherwise noted all columns must contain a value. Note that an empty string, the series of characters consisting of zero characters, is a value. The empty string[3] is a string and so it is reasonable to compare it with other non-empty strings. The empty string is distinct from NULL[4], which means “no information”, and is used when there is no value/no data at all.

Data consistency is guaranteed only when the guarantee is explicitly mentioned.[5] Care must be taken when updating data unless there is an explicit guarantee of data consistently.

This document uses a particular vocabulary, which informs the table names within the database. The selection of the vocabulary is based on the terminology in use at the JGI and may need some study for those not familiar with it.

A Guide for the Reader

This is a reference document, and as such is not expected to be read from front-to-back.

That said, the recommenced approach for someone new to SokweDB is to:

  • Skim thorough the next section’s (System Design) overview, but read all the detail in the About sub-sections.

  • Read the section and sub-section headings in the System Architecture section. Read in full whatever (sub-)sections are of interest, but at least scan the Databases and Schemas sections.

  • Scan the Entity Relationship Diagrams, and the key, only to get a sense of what that part of the documentation looks like.

    Refer back to the diagrams when necessary while reading the rest of the documentation

  • Read the entirety of the Views and SokweDB’s Structure section, its sub-sections, and the documentation of the various views found therein.

    The Views and SokweDB’s Structure section is different from the rest of the documentation in that it is, in some way, a tutorial. Rather than present views alphabetically, this section’s table of contents structures the presentation order to guide the reader’s understanding of the entire system.

  • Read the introductory paragraph of each table in the Data Tables section to familiarize yourself with the broad outlines of where data is kept.

After that, the reader should have enough background to explore whatever other parts of the documentation that are of interest, when they become of interest.

It wouldn’t hurt to try logging in to the database and executing example queries while reading.

Care must be taken when querying columns which allow NULL values. SQL uses a three valued logic, the values being TRUE, FALSE, and NULL. This only comes into play when a NULL value is encountered but can be a particularly important factor when a single query relates multiple tables.

Footnotes

Page last generated: 2026-07-26 00:41:56 UTC