Method: Search Events - JS/TS

async search(request: Search): Promise<SearchResult>

Parameter	Type	Description
request	Search	Event search parameters

A method of the Event Agent.

Search events in the event store that fit the search parameters.

Returns type SearchResult, which includes an array of queried events.

Parameter Type

Search

Importable from @fstnetwork/loc-logic-sdk

Event search parameters. If one search parameter have no conditions, set it to null.

Property	Type	Description
queries?	Query[] | null	Query conditions
excludes?	Query[] | null	Exclude conditions
filters?	Filter[] | null	Filter conditions
sort?	Sort[] | null	Sort conditions
aggregation?	Aggregation | null	Aggregation syntax
from?	number | null	Return events start from nth queried result
size?	number | null	Maximum query size

Sub Parameter Type

Query

Conditions to match (or not match) value in specific fields. All conditions will be applied for searching events.

type Query =
    | {
          field: string;
          type: "match";
          value: string;
      }
    | {
          field: string;
          type: "match_phrase";
          value: string;
      }
    | {
          field: string;
          type: "term";
          value: string;
      };

Fields	Description
field	Event field name
type	Match type ("match", "match_phrase" or "term")
value	string value to be matched

The three match types are based on Elasticsearch API:

• match: the value matches any word in the field (fuzzy search). Standard full-text search, suitable for most use cases.
• match_phrase: words order in the value matches words order in the field. For example, value "has been" matches it has been raining.
• term: the value matches exactly to the field.

Filter

Conditions to filter value in specific fields using either range filter or wildcard filter. All conditions will be applied for filtering events.

type Filter =
    | {
          field: string;
          gte?: number | null;
          lte?: number | null;
          type: "range";
      }
    | {
          field: string;
          type: "wildcard";
          value: string;
      };

Fields	Type	Description
field	string	Event field name
type	string	Filter type ("range" or "wildcard")
gte?	number | null	(Range filter only) greater than or equal to (null = no limit)
lte?	number | null	(Range filter only) less than or equal to (null = no limit)
value	string	(Wildcard filter only) Value with wildcard operators to be matched

The wildcard filter value can contain the following operators:

• ?: any single character
• *: zero to more than one characters

For example, event-?-* matches event-A-1 and event-B-123, etc.

Sort

Conditions to sort events by specific fields. All conditions will be applied for sorting events.

interface Sort {
    field: string;
    order: SortOrder;
}

type SortOrder = "asc" | "desc";

Sort Order	Description
"asc"	Ascending
"desc"	Descending

Aggregation

interface Aggregation {
    after?: {
        [k: string]: string;
    };
    queries: Query[];
    size?: number | null;
}

Return Type

SearchResult

Importable from @fstnetwork/loc-logic-sdk

Search result of matched events.

Property	Type	Description
events	Event[]	Queried events (empty array if none matches)
count	number	Number of events to be queried (size parameter from Search)
total	number	Actual queried number of events
took	number	Query time (milliseconds)
aggregation?	AggregationResult | null	Aggregation results

Sub Return Types

Event

Queried event object.

info

Not to be confused with Event.Event for emit(). The properties are not the field names for query, exclude, filter or sort conditions either.

Property	Type	Description
label	Label	Event label
sourceDigitalIdentity	string	Source digital identity
targetDigitalIdentity	string	Target digital identity
meta	string	Meta
type	number	Type or group
timestamp	string	Emit timestamp
sequence	string	Emit sequence
executionId	string	Execution ID
taskId	string	Task ID
dataProcessIdentityContext	VersionedIdentityContext	Data process identity
logicIdentityContext	VersionedIdentityContext	Logic identity

Label

Event label id/name.

Property	Type	Description
id	string	Event label ID
name	string	Event label name

VersionedIdentityContext

Refer to: VersionedIdentityContext

AggregationResult

interface AggregationResult {
    after: {
        [k: string]: string;
    };
    buckets: Bucket[];
    [k: string]: unknown;
}

Examples

Search Events

const query = await EventAgent.search({
    queries: [
        {
            field: "label_name",
            type: "match",
            value: "some label name",
        },
        {
            field: "source_digital_identity",
            type: "match",
            value: "some source DID",
        },
        // more match conditions...
    ],
    excludes: null,
    filters: null,
    sorts: null,
    aggregation: null,
    from: 0,
    size: 1000,
});

const events = query?.events;

// iterate through events
events.forEach((event) => {
    const labelName = event.label.name;
    const meta = event.meta;
    const logicPid = event.logicIdentityContext.permanentIdentity;
    // ...
});

Exclude Events

const query = await EventAgent.search({
    queries: null,
    excludes: [
        {
            field: "target_digital_identity",
            type: "match",
            value: "some target DID",
        },
        // more exclude conditions...
    ],
    filters: null,
    sorts: null,
    aggregation: null,
    from: 0,
    size: 1000,
});

const events = query?.events;

Filter Events

Filter with Range

Filter events emitted in the past hour (the timestamp field can be compared using unix time):

const query = await EventAgent.search({
    queries: null,
    excludes: null,
    filters: [
        {
            field: "timestamp",
            gte: Date.now() - 60 * 60 * 1000,
            lte: Date.now(),
            type: "range",
        },
        // more filter conditions...
    ],
    sorts: null,
    aggregation: null,
    from: 0,
    size: 1000,
});

const events = query?.events;

Filter with Wildcard

const query = await EventAgent.search({
    queries: null,
    excludes: null,
    filters: [
        {
            field: "label_name",
            type: "wildcard",
            value: "some?name*",
        },
        // more filter conditions...
    ],
    sorts: null,
    aggregation: null,
    from: 0,
    size: 1000,
});

const events = query?.events;

Sort Events

const query = await EventAgent.search({
    queries: null,
    excludes: null,
    filters: null,
    sorts: [
        {
            field: "target_digital_identity",
            order: "desc",
        },
        // more sort conditions...
    ],
    aggregation: null,
    from: 0,
    size: 1000,
});

const events = query?.events;