GFQL Attribute Matchers

GFQL Attribute Matchers#

For cross-step comparisons, use g.gfql([…], where=[…]) (or the explicit Chain(…, where=[…]) form); see GFQL WHERE (Same-Path Constraints).

Categorical#

class graphistry.compute.predicates.categorical.Duplicated(keep='first')

Bases: ASTPredicate

Parameters:

keep (Literal['first', 'last', False])

graphistry.compute.predicates.categorical.duplicated(keep='first')

Return whether a given value is duplicated

Parameters:

keep (Literal['first', 'last', False])

Return type:

Duplicated

Is In#

class graphistry.compute.predicates.is_in.IsIn(options)

Bases: ASTPredicate

Parameters:

options (List[int | float | str | number | None | Timestamp | datetime | date | time | DateTimeWire | DateWire | TimeWire | TemporalValue])

to_json(validate=True)

Override to handle temporal values in options

Return type:

dict

graphistry.compute.predicates.is_in.is_in(options)
Parameters:

options (List[int | float | str | number | None | Timestamp | datetime | date | time | DateTimeWire | DateWire | TimeWire | TemporalValue])

Return type:

IsIn

Numeric#

class graphistry.compute.predicates.numeric.Between(lower, upper, inclusive=True)

Bases: ASTPredicate

Parameters:

  • lower (float)

  • upper (float)

  • inclusive (bool)

class graphistry.compute.predicates.numeric.EQ(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a == b.

class graphistry.compute.predicates.numeric.GE(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a >= b.

class graphistry.compute.predicates.numeric.GT(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a > b.

class graphistry.compute.predicates.numeric.IsNA

Bases: ASTPredicate

class graphistry.compute.predicates.numeric.LE(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a <= b.

class graphistry.compute.predicates.numeric.LT(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a < b.

class graphistry.compute.predicates.numeric.NE(val)

Bases: NumericASTPredicate

Parameters:

val (int | float)

static op(a, b, /)

Same as a != b.

class graphistry.compute.predicates.numeric.NotNA

Bases: ASTPredicate

class graphistry.compute.predicates.numeric.NumericASTPredicate(val)

Bases: ASTPredicate

Parameters:

val (int | float)

op: ClassVar[Any]
graphistry.compute.predicates.numeric.between(lower, upper, inclusive=True)

Return whether a given value is between a lower and upper threshold

Parameters:

  • lower (float)

  • upper (float)

  • inclusive (bool)

Return type:

Between

graphistry.compute.predicates.numeric.eq(val)

Return whether a given value is equal to a threshold

Parameters:

val (float)

Return type:

EQ

graphistry.compute.predicates.numeric.ge(val)

Return whether a given value is greater than or equal to a threshold

Parameters:

val (float)

Return type:

GE

graphistry.compute.predicates.numeric.gt(val)

Return whether a given value is greater than a threshold

Parameters:

val (float)

Return type:

GT

graphistry.compute.predicates.numeric.isna()

Return whether a given value is NA

Return type:

IsNA

graphistry.compute.predicates.numeric.le(val)

Return whether a given value is less than or equal to a threshold

Parameters:

val (float)

Return type:

LE

graphistry.compute.predicates.numeric.lt(val)

Return whether a given value is less than a threshold

Parameters:

val (float)

Return type:

LT

graphistry.compute.predicates.numeric.ne(val)

Return whether a given value is not equal to a threshold

Parameters:

val (float)

Return type:

NE

graphistry.compute.predicates.numeric.notna()

Return whether a given value is not NA

Return type:

NotNA

String Predicates#

class graphistry.compute.predicates.str.Contains(pat, case=True, flags=0, na=None, regex=True)

Bases: ASTPredicate

Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

  • regex (bool)

class graphistry.compute.predicates.str.Endswith(pat, case=True, na=None)

Bases: _BoundaryStringPredicate

Parameters:

  • pat (str | tuple)

  • case (bool)

  • na (bool | None)

class graphistry.compute.predicates.str.Fullmatch(pat, case=True, flags=0, na=None)

Bases: _RegexStringPredicate

Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

class graphistry.compute.predicates.str.IsAlnum

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsAlpha

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsDecimal

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsDigit

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsLower

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsNull

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsNumeric

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsSpace

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsTitle

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.IsUpper

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.Match(pat, case=True, flags=0, na=None)

Bases: _RegexStringPredicate

Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

class graphistry.compute.predicates.str.NeverMatch

Bases: ASTPredicate

class graphistry.compute.predicates.str.NotNull

Bases: _CallablePredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.str.Startswith(pat, case=True, na=None)

Bases: _BoundaryStringPredicate

Parameters:

  • pat (str | tuple)

  • case (bool)

  • na (bool | None)

graphistry.compute.predicates.str.contains(pat, case=True, flags=0, na=None, regex=True)

Return whether a given pattern or regex is contained within a string

Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

  • regex (bool)

Return type:

Contains

graphistry.compute.predicates.str.endswith(pat, case=True, na=None)

Return whether a given pattern or tuple of patterns is at the end of a string.

Parameters:

  • pat (str | tuple) – Pattern (str) or tuple of patterns to match at end of string. When tuple, returns True if the string ends with ANY pattern (OR logic).

  • case (bool) – If True, case-sensitive matching (default: True).

  • na (bool | None) – Fill value for missing values (default: None).

Returns:

Endswith predicate.

Return type:

Endswith

Examples#

>>> n({"email": endswith(".com")})
>>> n({"email": endswith(".COM", case=False)})
>>> n({"filename": endswith((".txt", ".csv"))})
>>> n({"filename": endswith((".TXT", ".CSV"), case=False)})
graphistry.compute.predicates.str.fullmatch(pat, case=True, flags=0, na=None)

Return whether a given pattern matches the entire string

Unlike match() which matches from the start, fullmatch() requires the pattern to match the entire string. This is useful for exact validation of formats like emails, phone numbers, or IDs.

Args:

pat: Regular expression pattern to match against entire string case: If True, case-sensitive matching (default: True) flags: Regex flags (e.g., re.IGNORECASE, re.MULTILINE) na: Fill value for missing values (default: None)

Returns:

Fullmatch predicate

Examples:
>>> # Exact digit match
>>> n({"code": fullmatch(r"\d{3}")})  # Matches "123" but not "123abc"
>>>
>>> # Case-insensitive email validation
>>> n({"email": fullmatch(r"[a-z]+@[a-z]+\.com", case=False)})
>>>
>>> # With regex flags
>>> import re
>>> n({"id": fullmatch(r"[A-Z]{3}-\d{4}", flags=re.IGNORECASE)})
Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

Return type:

Fullmatch

graphistry.compute.predicates.str.isalnum()

Return whether a given string is alphanumeric

Return type:

IsAlnum

graphistry.compute.predicates.str.isalpha()

Return whether a given string is alphabetic

Return type:

IsAlpha

graphistry.compute.predicates.str.isdecimal()

Return whether a given string is decimal

Return type:

IsDecimal

graphistry.compute.predicates.str.isdigit()

Return whether a given string is numeric

Return type:

IsDigit

graphistry.compute.predicates.str.islower()

Return whether a given string is lowercase

Return type:

IsLower

graphistry.compute.predicates.str.isnull()

Return whether a given string is null

Return type:

IsNull

graphistry.compute.predicates.str.isnumeric()

Return whether a given string is numeric

Return type:

IsNumeric

graphistry.compute.predicates.str.isspace()

Return whether a given string is whitespace

Return type:

IsSpace

graphistry.compute.predicates.str.istitle()

Return whether a given string is title case

Return type:

IsTitle

graphistry.compute.predicates.str.isupper()

Return whether a given string is uppercase

Return type:

IsUpper

graphistry.compute.predicates.str.match(pat, case=True, flags=0, na=None)

Return whether a given pattern is at the start of a string

Parameters:

  • pat (str)

  • case (bool)

  • flags (int)

  • na (bool | None)

Return type:

Match

graphistry.compute.predicates.str.never_match()
Return type:

NeverMatch

graphistry.compute.predicates.str.notnull()

Return whether a given string is not null

Return type:

NotNull

graphistry.compute.predicates.str.startswith(pat, case=True, na=None)

Return whether a given pattern or tuple of patterns is at the start of a string.

Parameters:

  • pat (str | tuple) – Pattern (str) or tuple of patterns to match at start of string. When tuple, returns True if the string starts with ANY pattern (OR logic).

  • case (bool) – If True, case-sensitive matching (default: True).

  • na (bool | None) – Fill value for missing values (default: None).

Returns:

Startswith predicate.

Return type:

Startswith

Examples#

>>> n({"name": startswith("John")})
>>> n({"name": startswith("john", case=False)})
>>> n({"filename": startswith(("test_", "demo_"))})
>>> n({"filename": startswith(("TEST", "DEMO"), case=False)})

Temporal#

class graphistry.compute.predicates.temporal.IsLeapYear

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsMonthEnd

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsMonthStart

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsQuarterEnd

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsQuarterStart

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsYearEnd

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

class graphistry.compute.predicates.temporal.IsYearStart

Bases: _DatetimePropertyPredicate

static predicate(s)
Parameters:

s (Any)

Return type:

Any

graphistry.compute.predicates.temporal.is_leap_year()

Return whether a given value is a leap year

Return type:

IsLeapYear

graphistry.compute.predicates.temporal.is_month_end()

Return whether a given value is a month end

Return type:

IsMonthEnd

graphistry.compute.predicates.temporal.is_month_start()

Return whether a given value is a month start

Return type:

IsMonthStart

graphistry.compute.predicates.temporal.is_quarter_end()

Return whether a given value is a quarter end

Return type:

IsQuarterEnd

graphistry.compute.predicates.temporal.is_quarter_start()

Return whether a given value is a quarter start

Return type:

IsQuarterStart

graphistry.compute.predicates.temporal.is_year_end()

Return whether a given value is a year end

Return type:

IsYearEnd

graphistry.compute.predicates.temporal.is_year_start()

Return whether a given value is a year start

Return type:

IsYearStart

Temporal Values#

class graphistry.compute.ast_temporal.DateTimeValue(value, timezone='UTC')

Bases: TemporalValue

Tagged datetime value with timezone support

Parameters:

  • value (str)

  • timezone (str)

as_pandas_value()

Convert to pandas-compatible value for comparison

Return type:

Timestamp

classmethod from_datetime(dt)

Create from Python datetime

Parameters:

dt (datetime)

Return type:

DateTimeValue

classmethod from_pandas_timestamp(ts)

Create from pandas Timestamp

Parameters:

ts (Timestamp)

Return type:

DateTimeValue

to_json()

Return dict for tagged temporal value

Return type:

DateTimeWire

class graphistry.compute.ast_temporal.DateValue(value)

Bases: _ScalarTemporalValue

Tagged date value

Parameters:

value (str)

as_pandas_value()

Convert to pandas-compatible value for comparison

Return type:

Timestamp

classmethod from_date(d)

Create from Python date

Parameters:

d (date)

Return type:

DateValue

class graphistry.compute.ast_temporal.TemporalValue

Bases: ABC

Base class for temporal values with tagging support

abstract as_pandas_value()

Convert to pandas-compatible value for comparison

Return type:

Any

abstract to_json()

Serialize to JSON-compatible dictionary

Return type:

DateTimeWire | DateWire | TimeWire

class graphistry.compute.ast_temporal.TimeValue(value)

Bases: _ScalarTemporalValue

Tagged time value

Parameters:

value (str)

as_pandas_value()

Convert to pandas-compatible value for comparison

Return type:

time

classmethod from_time(t)

Create from Python time

Parameters:

t (time)

Return type:

TimeValue

graphistry.compute.ast_temporal.temporal_value_from_json(d)

Factory function to create temporal value from JSON dict

Parameters:

d (Dict[str, Any])

Return type:

TemporalValue