Querying Provenance¶
Currently Chronicle has 7 root queries.
type Query {
activityTimeline(
activityTypes: [ActivityType!]
forEntity: [EntityIdOrExternal!]
forAgent: [AgentIdOrExternal!]
from: DateTime
to: DateTime
order: TimelineOrder
namespace: ID
after: String
before: String
first: Int
last: Int
): ActivityConnection!
agentsByType(
agentType: AgentType!
namespace: ID
after: String
before: String
first: Int
last: Int
): AgentConnection!
activitiesByType(
activityType: ActivityType!
namespace: ID
after: String
before: String
first: Int
last: Int
): ActivityConnection!
entitiesByType(
entityType: EntityType!
namespace: ID
after: String
before: String
first: Int
last: Int
): EntityConnection!
agentById(id: AgentIdOrExternal!, namespace: String): Agent
activityById(id: ActivityIdOrExternal!, namespace: String): Activity
entityById(id: EntityIdOrExternal!, 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 ProvActivity activity type can be used to
return activities that are not currently specified in the Chronicle domain.
enum ActivityType {
ProvActivity
PublishedActivity
QuestionAskedActivity
ResearchedActivity
RevisedActivity
}
EntityIdOrExternal¶
A list of EntityIDs or externalIds 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. Not 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.
activitiesByType¶
An activity could be defined like so:
mutation {
defineItemCertifiedActivity(
externalId: "certification1",
attributes: { certIdAttribute: "123" }
) {
context
}
}
A user could query all activities of that type as in the following example:
query {
activitiesByType(activityType: ItemCertifiedActivity) {
nodes {
...on ItemCertifiedActivity {
id
certIdAttribute
}
}
}
}
agentsByType¶
An agent could be defined like so:
mutation {
defineContractorAgent(
externalId: "contractor1",
attributes: { locationAttribute: "Shenzhen" }
) {
context
}
}
A user could query all agents of that type as in the following example:
query {
agentsByType(agentType: ContractorAgent) {
nodes {
...on ContractorAgent {
id
location
}
}
}
}
entitiesByType¶
An entity could be defined like so:
mutation {
defineCertificateEntity(
externalId: "testentity1",
attributes: { certIdAttribute: "something" }
) {
context
}
}
A user could query all entities of that type as in the following example:
query {
entitiesByType(entityType: CertificateEntity) {
nodes {
...on CertificateEntity {
id
}
}
}
}
activityById¶
An activity could be defined like so:
mutation {
defineItemCertifiedActivity(
externalId: "externalid",
attributes: { certIdAttribute: "234" }
) {
context
}
}
A user could query that activity in the following way:
query {
activityById(id: {externalId: "externalid" }) {
... on ItemCertifiedActivity {
id
externalId
certIdAttribute
}
}
}
agentById¶
An agent could be defined like so:
mutation {
defineContractorAgent(
externalId: "externalId",
attributes: { locationAttribute: "location" }
) {
context
}
}
A user could query that agent in the following way:
query {
agentById(id: {externalId: "externalid" }) {
... on ContractorAgent {
id
externalId
locationAttribute
}
}
}
entityById¶
An entity could be defined like so:
mutation {
defineItemEntity(
externalId: "externalid",
attributes: { partIdAttribute: "432" }
) {
context
}
}
A user could query that activity in the following way:
query {
entityById(id: {externalId: "externalid" }) {
... on ItemEntity {
id
externalId
partIdAttribute
}
}
}
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 GuidanceEntity {
id: EntityID!
namespace: Namespace!
externalId: String!
type: DomaintypeID
evidence: Evidence
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 externalId, 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: externalId¶
The externalId 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¶
Still in development, see attachments and discussion of planned behavior. Querying presently takes the form:
query {
entityById(id: { externalId: "anaphylaxis-evidence-12114" }) {
... on ExperimentEntity {
evidence {
signature
signatureTime
locator
}
}
}
}
Entity: identity¶
Still in development, see discussion of planned behavior. Querying presently takes the form:
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 PublishedActivity {
id: ActivityID!
namespace: Namespace!
externalId: String!
started: DateTime
ended: DateTime
type: DomaintypeID
wasAssociatedWith: [Association!]!
used: [Entity!]!
wasInformedBy: [Activity!]!
generated: [Entity!]!
versionAttribute: VersionAttribute
}
Activity: id¶
The ActivityID of the activity. This is derived from externalId, but clients should not attempt to synthesize it themselves.
Activity: namespace¶
The Namespace of the activity, only of interest for Chronicle domains that span multiple namespaces.
Activity: externalId¶
The externalId of the activity, determined when defined.
Activity: type¶
A DomainTypeID derived from the Activity subtype. The built-in GraphQL field
__TypeName should be used for union queries