Agree on API for agent event queries

[pospi]

Shroom has agentEconomicEvents(latestNumberOfDays: 30), which seems like an older API.

My vote currently goes to something like:

input agentEventSearchParams {
  searchString: String
  action: ID
  startDate: DateTime
  endDate: DateTime
}
interface Agent {
    economicEvents(filter: agentEventSearchParams, start: ID, limit: Int)
}

Also see this as a general format for graph search edges. This way, we can iteratively add filter criteria without upsetting existing code.

We would also need to define what searchString is supposed to match in all cases.

[fosterlynn]

@pospi

We would also need to define what searchString is supposed to match in all cases.

What kinds of things would go in searchString, as opposed to the parameters with specific definitions?

Also see this as a general format for graph search edges. This way, we can iteratively add filter criteria without upsetting existing code.

:+1:

which seems like an older API

It definitely is an older api, let's change all of those.

[pospi]

"Parameters with specific definitions" sounds like exactly this. I pulled the text stuff out of here into https://github.com/valueflows/vf-apps/issues/7 - that's a separate issue (:

[pospi]

Updated parameters suggestion after reflecting on some UI code and the query edges that seem to be most needed:

enum AgentRelationshipType {
  PROVIDER
  RECEIVER
}
input agentEventSearchParams {
  searchString: String
  startsOnOrBefore: DateTime
  startsOnOrAfter: DateTime
  endsOnOrBefore: DateTime
  endsOnOrAfter: DateTime
  involvementType: AgentRelationshipType # if ommitted, shows all related events
  accountingScopeIn: [ID!]  # this matches agents inScopeOf. Should we change the name and match on provider/receiver too?
  actionIn: [ID!]
  inputProcessIn: [ID!]
  outputProcessIn: [ID!]
  affectedResourceIn: [ID!]  # this would match toInventoriedResource as well?
  resourceSpecificationIn: [ID!]
  resourceClassificationIn: [URI!]
  realizedAgreementIn: [ID!]
  triggeringEventIn: [ID!]
  locationIn: [ID!]
  fulfillsCommitmentIn: [ID!] # these should query on the flow record IDs, not the relationship records?
  satisfiesIntentIn: [ID!]
}

Emerging general patterns:

• All top-level filter criteria are compared using a boolean logical AND (all criteria must match). To perform OR queries, clients can simply make multiple separate requests and merge the results.
• Array parameters are most often used instead of individual IDs, and the matching is logical OR (any of the provided values will match). This format enables clients to combine multiple queries into the same requests in many cases. Criteria which behave in this way are suffixed with In.
• The 4 date fields provide a balance between simplicity and flexibility when performing queries against records with mixed ranged and instance dates. Range computations would depend on the format passed. Best illustrated by example:
  • all events that ran entirely within a given day: startsOnOrAfter 2020-01-01, endsOnOrBefore 2020-01-01
  • events that happened within the same second: startsOnOrAfter 2020-01-01 12:00:00, endsOnOrBefore 2020-01-01 12:00:00
  • events that happened at an "exact" moment (within 1/1000s): startsOnOrAfter 2020-01-01 12:00:00.000, endsOnOrBefore 2020-01-01 12:00:00.000
  • events that began on or occurred after a particular date: startsOnOrAfter 2020-01-01
  • events that began at or occurred after a particular moment in time: startsOnOrAfter 2020-01-01 12:00:00.000
  • all events that finished today, regardless of when they started: endsOnOrBefore 2020-01-01 endsOnOrAfter 2020-01-01
  • all events that finished today, which have a known start time: endsOnOrBefore 2020-01-01 endsOnOrAfter 2020-01-01 startsOnOrBefore 2020-01-01
  • all events that started today, regardless of when (and if) they finished: startsOnOrBefore 2020-01-01 startsOnOrAfter 2020-01-01
  • all events that started today, which have also finished: startsOnOrBefore 2020-01-01 startsOnOrAfter 2020-01-01 endsOnOrAfter 2020-01-01
  • all events which were occurring in a given week: startsOnOrBefore 2020-01-08 endsOnOrAfter 2020-01-01
  • all events which were occurring at a given moment: startsOnOrBefore 2020-01-08 12:00:00.000 endsOnOrAfter 2020-01-08 12:00:00.000
  • Please check my logic... I'm not too sure about any of this, if there is existing ontology we can pull from that would be ideal. The interval relationships in the OWL Time Ontology might be a useful resource if gaps in the above become apparent...

Specific thoughts about this API:

• eventLocationIn is given as an ID list rather than with geospatial indexing search criteria. This leaves it the responsibility of the geolocation module how to resolve location IDs and support area-based (and other advanced geospatial) queries, after which the queries into the event ledger become simple checks against the computed IDs.
• The top-level event query parameters for Query.economicEventsFiltered should probably be the same, except for replacement of involvementType with providingAgentIn: [ID!], receivingAgentIn: [ID!] to allow querying on these fields rather than reading from the context Agent.

Other questions:

• You can currently have open-ended events... just want to check that this is expected behaviour.
• Are "provider" and "receiver" the only relationships that should determine what is searched for agent-based queries? Is the way that inScopeOf is configured above appropriate?

[pospi]

I also haven't done any query parameters for quantities. Some input on what may be needed there would be good to have.

[fosterlynn]

Are "provider" and "receiver" the only relationships that should determine what is searched for agent-based queries?

No, if you are creating accounting reports for example, you would get all events within a scope. And for lots of other UIs too.

I also haven't done any query parameters for quantities. Some input on what may be needed there would be good to have.

One that comes to mind is that most "normal" queries will not want zero quantity resources, but maybe sometimes people would want to include those? But let's do that "normal" thing, and then let's wait and see what else is needed. I would say that to lots of things actually. If we can work directly with the first few groups, we'll know a lot more. I can plug into some of that too, as it makes sense.

You can currently have open-ended events... just want to check that this is expected behaviour.

You mean like a start time without a matching end time? It doesn't make sense for an event, but we need to allow it to account for apps that save during events, like timers.

accountingScopeIn: [ID!] # this matches agents inScopeOf. Should we change the name and match on provider/receiver too?

Anything wrong with naming it inScopeOf? I guess adding provider/receiver would capture transfers, which don't really have a scope. I'm trying to think of reasons not to do that, but don't come up with any atm.

affectedResourceIn: [ID!] # this would match toInventoriedResource as well?

Seems like it.

Not sure I get the use of "XIn" naming of a lot of those parameters?

fulfillsCommitmentIn: [ID!] # these should query on the flow record IDs, not the relationship records?

Don't understand the question? Are you trying to get all the events that fulfill a commitment?

The interval relationships in the OWL Time Ontology might be a useful resource if gaps in the above become apparent...

That is one of the main reasons we went with OWL Time. There might be services where we could just ask, but I don't know.

all events that finished today, which have a known start time:

That one seems excessive, is there a reason to worry about having a known start time? Also the corresponding starts one. I don't think we want to imply anything about other parameters within one parameter?

[pospi]

RE accounting scopes, I think it makes more sense to do those as top-level queries rather than via an agent record edge. Does it work for you if we service those kinds of queries like this?-

type eventSearchParams {
    providingAgentIn: [ID!]
    receivingAgentIn: [ID!]
    inScopeOf: [ID!]    

    # (rest is more or less the same as `agentEventSearchParams` from above, ommitting `involvementType`)
}

type Query {
    economicEventsFiltered(filter: eventSearchParams)
}

RE xIn as parameter naming: I was attempting to plan ahead for queries where multiple values would be of interest- because if you allow an array, then you can use the same API with 1-element arrays to query for single values. It's just more flexible.

First question: do we want such functionality, or do we only allow matching on single values at the moment?

Second question: should we drop the "In" suffix and just use the field names, and indicate in the documentation that if array values are provided in queries that any value in the array will be matched?

Other stuff....

Are you trying to get all the events that fulfill a commitment?

Yes. So I'm wondering whether to pass the fulfillment or commitment ID when doing the search.

is there a reason to worry about having a known start time?

Probably not for events, but maybe for commitments or intents? Regardless, I want to keep these parameters consistent for all time-related fields so that only one convention has to be learned. The examples may not necessarily make sense for events, I am just trying to define all cases that might need querying to ensure that these parameters could service them.

[pospi]

Closing this issue to defer it for now; we'll approach these questions in a much more piecemeal manner.