Core Concepts

The Output Database implements the relational database model that stores the structured JSON output returned by the NLP API. Hence, it is helpful to have a high-level understanding of the data model of the NLP API’s JSON result format. For a more complete explanation, see Understanding the NLP API Output. Here, we provide a quick recap of the key points.

A single JSON file is returned for every processing request. The JSON file may contain multiple Document objects if multiple reports were sent for processing in the same request. Each Document object contains the structured output from one report in the processing request. The following list identifies the key objects and attributes present in the NLP API’s JSON output.

• A Document contains many Entities and Relations.
• An Entity can be associated with zero or more Concepts.
• Concepts are associated with an ontology, an ontology-specific concept ID and a description. For example in SNOMED-CT a term with concept ID of 241580002 has a fully-specified name of Computed tomography of lumbar spine (procedure).
• In addition to Concepts, an Entity may also be associated with the following information:
  • Entity type(s) - the semantic type of the entity as defined by the related ontology.
  • Text - the annotated text for the extracted Entity.
  • Span - the start and end offset of the text from the beginning of the document’s raw text.
  • Section - the section within a report where the entity was found. As you will see later, sections provide important context for analysis of entity occurrences.
  • Attributes - An entity may have attributes such as:
    • Polarity
    • Uncertainty
    • Measurement units
• A Document has many Locations.
  • Each Location refers to a sentence or section and its offsets from the beginning of the document.

In the following sections, we will explain how the NLP API’s result data is stored in the NLP API’s database tables. The documentation is organized into three major areas: Entity-level tables, Document-level tables and Relation feature tables. The following ER diagram gives a conceptual view of this organization showing the key objects and attributes in each area.