Relation¶

bcql_py.models.relation ¶

Relations model grammatical dependencies (or other relations) between tokens / spans. The --> operator connects a source to a target via a named relation type.

The idea here is that we can have one "source" with multiple relation constraints on it, like

_ -nsubj-> _ ; !-obj-> "dog"

where there must be a subj relationship but where dog must not be an obj. (It does NOT imply that the word "dog" must be present.)

RelationOperator ¶

Bases: BCQLNode

The operator in a relation query: -type-> or !-type->. See https://github.com/instituutnederlandsetaal/BlackLab/blob/dev/site/docs/guide/040_query-language/020_relations.md#negative-child-constraints for details on negative relations.

Attributes:

Name	Type	Description
`relation_type`	`str \| None`	The relation type as a string or regex pattern (e.g. `"obj"`, `"subj\|obj"`), or `None` for any type.
`negated`	`bool`	`True` for `!-type->`.
`target_field`	`str \| None`	For cross-field relations (e.g. `-->corrected`), the target field name. `None` for same-field relations.

ChildConstraint ¶

Bases: BCQLNode

A single child constraint in a relation query.

Represents [-label:] -type-> target inside a relation expression. Multiple child constraints are separated by ;. The target itself can be any BCQL sub-query, including another relation query (e.g. _ -nsubj-> (_ -amod-> _)).

Attributes:

Name	Type	Description
`operator`	`RelationOperator`	The relation operator (type, negation, target field).
`target`	`BCQLNodeUnion`	The target sub-query.
`label`	`str \| None`	Optional capture label on this child relation (e.g. `rel:-obj-> _`).

RelationNode ¶

Bases: BCQLNode

A dependency relation query: source -type-> target [; -type-> target]*.

The source is specified once; one or more child constraints follow, separated by ;.

Attributes:

Name	Type	Description
`source`	`BCQLNodeUnion`	The source of the relation.
`children`	`list[ChildConstraint]`	One or more target constraints.

RootRelationNode ¶

Bases: BCQLNode

A root relation query: ^-type-> target or label:^-type-> target.

Usually this relation does not have a "type" (since ROOT is the dependency relation from the root), but some corpora may differ.

TODO: see if the Validator and CorpusSpec should account for "allowed root relations"

Root relations have no source, only a target. They match the root of a dependency tree.

Attributes:

Name	Type	Description
`relation_type`	`str \| None`	Optional relation type filter (usually `None` meaning any root).
`target`	`BCQLNodeUnion`	The target sub-query.
`label`	`str \| None`	Optional capture label.