@Marvin In designing automations' trigger in the YAML file, what is the significance & difference between 'match' and 'match-related'?

In Prefect 2.0 YAML automation triggers, both

match

and

match-related

are used to define criteria for which resources the automation should consider when determining whether to execute an action. They can each accept a list of multiple values. However, the documentation does not provide explicit definitions or differences between

match

and

match-related

within the provided excerpts. From the context, it seems that

match

and

match-related

are likely to be used to specify different types of matching criteria, possibly

match

for direct matches to the event-triggering resource and

match-related

for associated resources. Nevertheless, the documentation excerpts provided do not make clear distinctions between the two. To ensure the usefulness of the given information, it's important to note that for detailed and accurate usage, it would be advisable to refer to the official Prefect documentation or seek direct guidance from Prefect community resources. This would provide specific guidelines on how to use

match

and

match-related

in automation triggers correctly.

@Marvin Does the 'resources' you mentioned above refer to 'flows'?

In the context of Prefect 2.0 automations, the term "resources" refers to the objects that emit events. Resources are used as identifiers for sources of events, and they are constructed as dot-delimited strings. Examples include automation identifiers, user identifiers, and flow run identifiers like

prefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6

. As mentioned, every event has a primary resource, and resources can also have additional labels for use in event aggregation queries. This means that "resources" in Prefect 2.0 encompass more than just flows; they can refer to various objects within the Prefect ecosystem, including automations, users, flow runs, deployments, and work pools, among others. When an automation is triggered, it has access to information about the event that caused the trigger, including details about the primary resource and any related resources, providing a comprehensive context for the event.

marvin's generally right here, a flow is a type of resource. here's an example using

match-related

to define a deployment trigger

from datetime import timedelta
from prefect import flow, serve
from prefect.events.schemas import DeploymentTrigger

@flow(log_prints=True)
def upstream_foo():
    print("foo")
    
@flow(log_prints=True)
def upstream_bar():
    print("bar")

@flow(log_prints=True)
def upstream_baz():
    print("baz")

@flow(log_prints=True)
def downstream():
    print("i was triggered!")

trigger_on_upstream = DeploymentTrigger(
    name="Wait for N upstream deployments",
    enabled=True,
    match_related={ # match upstream deployments (where the Deployment is a `related resource` to the FlowRun)
        "prefect.resource.name": "upstream-*",
    },
    expect={"prefect.flow-run.Completed"}, # what events to wait for
    threshold=3, # how many such events to wait for
    within=timedelta(minutes=5), # the window of time within which matching events need to occur for this to trigger
)
    

if __name__ == '__main__':
    deployments = [
        (
            f.to_deployment(f.name)
            if f.name != "downstream"
            else f.to_deployment(f.name, triggers=[trigger_on_upstream])
        )
        for f in [upstream_foo, upstream_bar, upstream_baz, downstream]
    ]
    
    serve(*deployments)