Functions

BCQL supports a number of useful functions. Some functions produce queries as output, which you can use as part of a larger query; others produce values that you can pass to other functions.

Some of these functions exist in some form in other dialects of Corpus Query Language.

Functions to do with relations search are described there.

Query functions

The following functions can be used in the regular query part (before ::) to determine or change the hits to find.

cspan: adjust to capture

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

Occasionally, you might not want your hits to span your whole query, but you're just interested in one part of it. You can use the cspan() function to adjust the hit:

# Find adjectives with tree
cspan(A:[pos="ADJ"]+ "tree", "A")

The hits will be anything captured as A, so just the adjectives in this case.

(of course, the same result can often be achieved using a lookahead. In this case, you could use [pos="ADJ"]+ (?= "tree") to get the same hits)

meet: nearby words

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

You can use either the meet or the meet_within function to filter matches based on the presence of other words nearby.

For example, to find all occurrences of the word cat that are within 5 tokens of the word fluffy (before or after), you can use:

meet("cat", "fluffy", -5, 5)

To find occurrences of the phrase black dog with the word good occurring up to 10 tokens before it, use:

meet("black" "dog", "good", -10, -1)

To find occurrences of the word fish with the phrase in water occurring between 2 and 5 tokens after it (i.e. 1-4 tokens between fish and in):

meet("fish", "in" "water", 2, 5)

To find occurrences of platypus where weird does NOT occur within 5 tokens:

meet("platypus", !"weird", -5, 5)

How meet works

The meet function was inspired by the function with the same name in the Sketch Engine.

Note that the meet function is just syntactic sugar for a "regular" BCQL query. For example, meet("fish", "in" "water", 2, 5) is equivalent to:

"fish" (?= []{1,4} "in" "water" )

(read as: find those occurrences of fish that are followed by 1-4 tokens, followed by the phrase in water)

Different calls to meet and meet_within are rewritten to different queries, trying to choose the optimal variant for the situation.

meet_within: meet within boundary

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

You may only want to find words that occur in the same sentence. This is what meet_within is for. To find cat and fluffy in the same sentence:

meet_within("cat", "fluffy", <s/>)

To also require that they must occur within 5 words of each other:

meet_within("cat", "fluffy", <s/>, -5, 5)

To find cat provided that the sentence does not have fluffy within 5 words of it:

meet_within("cat", !"fluffy", <s/>, -5, 5)

union: combine matches

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

The union function allows you to combine matches from a list of queries into a single result set. For example, to find all occurrences of either fluffy cat or good dog, use:

union("fluffy" "cat", "good" "dog")

This is equivalent to the following query using the OR operator (|):

"fluffy" "cat" | "good" "dog"

The function is provided for those familiar with it from other corpus query languages.

Constraint functions

These are used in constraints (after ::), to operate on parts captured by the query.

start: start of capture

Within constraints, use start(A) to get the starting token position of capture A.

If A captured the first token of the document, start(A) would return 0.

end: end of capture

Within constraints, use end(A) to get the ending token position of capture A. Note that this is always the first token position AFTER the capture.

The first token in a document has token position 0, so if A captured the first two words of the document, end(A) would return 2 (the third token).

gap: gap between captures

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

To determine the gap between two captures:

gap(A, B, directional=false)

If A and B overlap or are contiguous, this will return 0.

Otherwise, if the optional argument directional is false (the default) it will determine the gap between A and B as a non-negative number. (To be precise, it calculates either end(B) - start(A) or end(A) - start(B), whichever is positive)

If directional is set to true, the gap will be negative if A comes after B.

Working with types

BCQL supports several basic types such as string, integer, boolean and list. These functions create or convert to specific types.

abs: absolute value

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

Calculates the absolute value of a number:

abs(-5)   # result 5

in_range: test if numbers are within a range

Checks if a number falls within a range (inclusive).

To check if capture A starts in the first 100 tokens in the document:

in_range(start(A), 0, 100)

This would be equivalent to start(A) >= 0 & start(A) <= 100. Using in_range can be convenient if the expression is longer, to avoid having to repeat it.

list: list of values

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

Some functions take a list of values as input. You can create such a list using the list function. For example, to pass multiple clauses to the union function, you could use:

union(list("cat", "dog"))

Note that you won't need list() to pass the function's final (or in this, only) parameter: anytime the final parameter to a function is of type list, you can simply pass a variable number of arguments and they will automatically be combined into a list. For example:

union("one", "two", "three")  # same as union(list("one", "two", "three"))

str: interpret as string

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

A quoted string in BCQL can be interpreted as either a string or a token query, depending on the context. For example, "duck" might mean [word="duck"] (a query), or it might just mean the simple string value. When building a list of strings, BlackLab doesn't know which one you mean, so you need to explicitly tell it. For example, to create a list of strings cat and dog, use:

list(str("cat"), str("dog"))

note that this is different from

list("cat", "dog")

which will create a list of token queries.

symbol: interpret as symbol

In-development feature

Try this feature on dev (Docker image or branch). It will be finalized for version 5.0.

To specify a symbol (e.g. an annotation) using a string:

[ symbol("word") = "cow" ]

is equivalent to

[ word = "cow" ]

For now, this mostly exists to prove that functions can return symbols, but it might prove useful in rare cases in the future.