Skip to content

Querying Provenance

Currently Chronicle has 4 root queries.

type Query {
    activityTimeline(activityTypes: [ActivityType!]!, forEntity: [EntityID!]!, from: DateTime, to: DateTime, namespace: ID, after: String, before: String, first: Int, last: Int): ActivityConnection!
    agentsByType(agentType: AgentType!, namespace: String, after: String, before: String, first: Int, last: Int): AgentConnection!
    agentById(id: AgentID!, namespace: String): Agent
    entityById(id: EntityID!, namespace: String): Entity
}

The majority of the work for provenance retrieval will be with the activity timeline query.

Familiarizing yourself with GraphQL is necessary to make good use of Chronicle. Chronicle makes extensive use of relay cursors and union types.

Activity timeline

Parameters

activityTypes

A list of ActivityTypes to filter the returned timeline by, leaving this empty will return all activity types. The PROV_ACTIVITY activity type can be used to return activities that are not currently specified in the Chronicle domain.

enum ActivityType {
  PROV_ACTIVITY
  PUBLISHED
  QUESTION_ASKED
  RESEARCHED
  REVISED
}

forEntity

A list of EntityIDs to filter activities by - leaving this empty will return all activity types.

from

The time in RFC3339 format to return activities from. Not specifying this will return all activity types before the time specified in to.

to

The time in RFC3339 format to return activities until. Nor specifying this will return all activity types after the time specified in from.

after

Relay cursor control, returning a page after the cursor you supply to this argument - for forwards pagination.

before

Relay cursor control, returning items before the cursor you supply to this argument - for reverse pagination.

first

An integer controlling page size for forward pagination. Defaults to 20

last

An integer controlling page size for reverse pagination. Defaults to 20

agentsByType

agentById

entityById

Returned objects

Entity subtypes

All Chronicle Entity subtypes follow a similar pattern, we will use the Guidance entity from our example domain as a sample.

type Guidance {
  id: EntityID!
  namespace: Namespace!
  name: String!
  type: DomaintypeID
  evidence: ChronicleEvidence
  wasGeneratedBy: [Activity!]!
  wasDerivedFrom: [Entity!]!
  hadPrimarySource: [Entity!]!
  wasRevisionOf: [Entity!]!
  wasQuotedFrom: [Entity!]!
  titleAttribute: TitleAttribute
  versionAttribute: VersionAttribute
}

Entity: id

The EntityID of the entity. This is derived from name, but clients should not attempt to synthesize it themselves.

Entity: namespace

The Namespace of the entity, only of interest for Chronicle domains that span multiple namespaces.

Entity: name

The name of the entity, determined when defined.

Entity: type

A DomainTypeID derived from the Entity subtype. The built-in GraphQL field __TypeName should be used for union queries.

Entity: evidence

See chronicle evidence

Entity: wasGeneratedBy

A list of the Activities that generated this entity. See generation.

Entity: wasRevisionOf

A list of the Entities that this entity is a revision of. See revision. This currently only returns the immediate entity that the current entity is derived from and will require recursive enumeration to retrieve a deep hierarchy.

Entity: wasQuotedFrom

A list of the Entities that this entity was quoted from. See quotation. This currently only returns the immediate entity that the current entity is derived from and will require recursive enumeration to retrieve a deep hierarchy.

Entity: wasDerivedFrom

A list of the Entities that this entity is derived from. See derivation. This currently only returns the immediate entity that the current entity is derived from and will require recursive enumeration to retrieve a deep hierarchy.

Attributes

Attribute values for the attributes associated with the entity subtype, as determined by the domain model.

Activity subtypes

type Published {
  id: ActivityID!
  namespace: Namespace!
  name: String!
  started: DateTime
  ended: DateTime
  type: DomaintypeID
  wasAssociatedWith: [Association!]!
  used: [Entity!]!
  versionAttribute: VersionAttribute
}

Activity: id

The EntityID of the entity. This is derived from name, but clients should not attempt to synthesize it themselves.

Activity: namespace

The Namespace of the entity, only of interest for Chronicle domains that span multiple namespaces.

Activity: name

The name of the entity, determined when defined.

Activity: type

A DomainTypeID derived from the Entity subtype. the built-in GraphQL field __TypeName should be used for union queries