Ontology Overview

The Ontology API provides access to the JARVIS knowledge graph -- a structured representation of entities and relationships extracted from financial events such as earnings calls, investor days, and conferences. Data is stored in Amazon Neptune as an RDF graph and queried using SPARQL.

SPARQL Fundamentals

SPARQL (SPARQL Protocol and RDF Query Language) is the W3C standard query language for RDF graph databases. It is conceptually similar to SQL but designed for querying data stored as triples.

Triples

All data in the knowledge graph is stored as triples -- statements with three parts:

Subject  ->  Predicate  ->  Object
(who)        (verb)         (what)

For example:

Tim Cook       works_for       Apple Inc
Apple Inc      competes_with   Microsoft
Tim Cook       discusses       Revenue Growth

Component	Description	Examples
Subject	The entity being described	`Tim Cook`, `Apple Inc`
Predicate	The relationship or property	`works_for`, `rdf:type`, `rdfs:label`
Object	The value or related entity	`Apple Inc`, `"Tim Cook"`, `aiera:PERSON`

URIs and Prefixes

Every resource in RDF has a unique URI. Prefixes are shortcuts that make queries readable.

Without prefix:

SELECT * WHERE {
  <http://aiera.com/ontology#Tim_Cook> <http://aiera.com/ontology#works_for> <http://aiera.com/ontology#Apple_Inc> .
}

With prefix:

PREFIX aiera: <http://aiera.com/ontology#>
SELECT * WHERE {
  aiera:Tim_Cook aiera:works_for aiera:Apple_Inc .
}

Auto-Injected Prefixes

The API automatically injects the following standard prefixes when they are used but not declared. You do not need to include PREFIX declarations for these:

Prefix	URI	Purpose	Reference
`rdf:`	`http://www.w3.org/1999/02/22-rdf-syntax-ns#`	Core RDF vocabulary	RDF Concepts
`rdfs:`	`http://www.w3.org/2000/01/rdf-schema#`	RDF Schema (labels, classes)	RDF Schema
`xsd:`	`http://www.w3.org/2001/XMLSchema#`	Data types (string, date, etc.)	XML Schema
`aiera:`	`http://aiera.com/ontology#`	JARVIS domain vocabulary	This document

This means you can write queries without explicit prefix declarations:

SELECT ?person ?company
WHERE {
  ?person rdf:type aiera:PERSON .
  ?person aiera:works_for ?company .
}

Variables

Variables start with ? and represent unknowns to be matched:

SELECT ?person ?company WHERE {
  ?person aiera:works_for ?company .
}

The pattern ?s ?p ?o is shorthand for Subject, Predicate, Object:

SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

Supported Query Types

Type	Description	Reference
`SELECT`	Returns variable bindings as a table	SELECT
`ASK`	Returns true/false for pattern existence	ASK
`CONSTRUCT`	Returns an RDF graph	CONSTRUCT
`DESCRIBE`	Returns RDF description of resources	DESCRIBE

Note

UPDATE operations (INSERT, DELETE, CLEAR, DROP) are blocked for safety. Only read queries are permitted.

JARVIS Ontology Schema

Entity Types

Entities are classified using rdf:type. The ontology defines 26 entity types across 6 categories:

Category	Types	Description
Core	`PERSON`, `ORGANIZATION`, `PRODUCT`, `LOCATION`, `TEMPORAL`, `EVENT`	Fundamental entity types
Business	`COMPETITOR`, `COMPETITIVE_PRODUCT`, `SUPPLIER`, `CUSTOMER`, `PEER`, `PARTNER`, `INDUSTRY_SEGMENT`	Business relationship entities
Financial	`REPORTED_METRIC`, `COMPANY_GUIDANCE`, `CONSENSUS_ESTIMATE`, `MARKET_METRIC`	Financial metrics and estimates
KPIs	`PRIMARY_KPI`, `INDUSTRY_KPI`, `OPERATIONAL_KPI`	Key performance indicators
Ownership	`SHAREHOLDER`, `ANALYST_FIRM`, `ANALYST_QUESTION`	Ownership and analyst coverage
Strategic	`STRATEGY`, `RISK`, `CATALYST`	Strategic planning concepts

Relationship Predicates

Relationships connect entities. The ontology defines 34 relationship predicates:

Category	Predicates
Employment	`works_for`, `leads`, `reports_to`, `serves_on_board`
Business	`competes_with`, `competes_with_product`, `peer_of`, `supplies_to`, `customer_of`, `partner_with`, `subsidiary_of`, `primary_player_in`, `secondary_player_in`
Financial	`reports_metric`, `provides_guidance`, `beats_estimate`, `misses_estimate`, `revises_guidance`, `has_target`
Ownership	`owns_shares_in`, `covers_stock`, `rates`
Events	`speaks_at`, `discusses`, `mentions`, `asks_about`, `extracted_from`
Strategic	`implements`, `faces`, `expects`, `invests_in`
Geographic	`operates_in`, `headquartered_in`, `expanding_to`

Common Properties

Property	Description	Example
`rdfs:label`	Human-readable name	`"Tim Cook"`
`aiera:role`	Person's role	`"CEO"`
`aiera:confidence`	Extraction confidence	`0.95`
`aiera:source`	Data source	`"earnings_call_12345"`
`aiera:timestamp`	When extracted	`"2024-01-15T10:30:00Z"`

Named Graphs

Data is organized into named graphs by event ID. Each event's extracted data is stored in GRAPH aiera:event/{event_id}, allowing you to query entities and relationships from specific events.

Reified Statements

Relationships include metadata via RDF reification -- confidence scores, effective dates, and provenance information are attached to relationship statements.

Best Practices

Always use LIMIT -- queries without a LIMIT clause can return very large result sets.
Be specific with patterns -- use rdf:type to narrow matches to specific entity types.
Filter early -- place FILTER clauses as close to the relevant triple patterns as possible.
Use OPTIONAL sparingly -- each OPTIONAL can multiply query execution time.
Select only needed variables -- SELECT ?name ?role is more efficient than SELECT *.