GFQL Operator Reference

This reference outlines the operators available in GFQL for constructing predicates in your graph queries. These operators are wrappers around Pandas/cuDF functions, allowing you to express complex filtering conditions intuitively. See the API reference documentation for more details on individual operators.

Operators

The following table lists the available operators, their descriptions, and examples of how to use them in GFQL.

Numeric and Comparison Operators

Note

All numeric comparison operators (gt, lt, ge, le, eq, ne, between) also support temporal values:

• DateTime: n({ "created_at": gt(pd.Timestamp("2023-01-01 12:00:00")) })

• Date: n({ "event_date": eq(date(2023, 6, 15)) })

• Time: n({ "daily_time": between(time(9, 0), time(17, 0)) })

See Working with Dates and Times for datetime filtering examples.

Categorical Operators

Operator	Description	Example
is_in(values)	Value is in values list.	n({ "type": is_in(["person", "company"]) })
is_not_in(values)	Value is not in values list.	n({ "type": is_not_in(["bot", "spam"]) })
duplicated(keep='first')	Marks duplicated values.	n({ "email": duplicated() })

String Operators

Operator	Description	Example
contains(pattern, case=True)	String contains pattern. Case-insensitive if case=False.	n({ "name": contains("smith", case=False) })
startswith(prefix, case=True)	String starts with prefix. Case-insensitive if case=False.	n({ "username": startswith("admin", case=False) })
endswith(suffix, case=True)	String ends with suffix. Case-insensitive if case=False.	n({ "email": endswith(".com", case=False) })
match(pattern, case=True)	String matches regex pattern from start. Case-insensitive if case=False.	n({ "phone": match(r"^\d{3}-\d{4}$") })
fullmatch(pattern, case=True)	String matches regex pattern entirely. Case-insensitive if case=False.	n({ "code": fullmatch(r"\d{3}", case=False) })
isnumeric()	String is numeric.	n({ "code": isnumeric() })
isalpha()	String is alphabetic.	n({ "code": isalpha() })
isdigit()	String is digit characters.	n({ "code": isdigit() })
islower()	String is lowercase.	n({ "tag": islower() })
isupper()	String is uppercase.	n({ "code": isupper() })
isspace()	String contains only whitespace.	n({ "comment": isspace() })
isalnum()	String is alphanumeric.	n({ "code": isalnum() })
isdecimal()	String is decimal characters.	n({ "number": isdecimal() })
istitle()	String is title-cased.	n({ "title": istitle() })

Null and NA Operators

Operator	Description	Example
isna()	Value is NA/NaN.	n({ "email": isna() })
notna()	Value is not NA/NaN.	n({ "email": notna() })
isnull()	Alias for isna().	n({ "email": isnull() })
notnull()	Alias for notna().	n({ "email": notnull() })

Temporal Operators

Operator	Description	Example
is_month_start()	Date is the first day of the month.	n({ "date": is_month_start() })
is_month_end()	Date is the last day of the month.	n({ "date": is_month_end() })
is_quarter_start()	Date is the first day of the quarter.	n({ "date": is_quarter_start() })
is_quarter_end()	Date is the last day of the quarter.	n({ "date": is_quarter_end() })
is_year_start()	Date is the first day of the year.	n({ "date": is_year_start() })
is_year_end()	Date is the last day of the year.	n({ "date": is_year_end() })
is_leap_year()	Date is in a leap year.	n({ "date": is_leap_year() })

Usage Examples

Example 1: Filtering Nodes with Numeric Conditions

from graphistry import n, gt, lt

# Find nodes where age is greater than 18 and less than 30
g_filtered = g.chain([
    n({ "age": gt(18) }),
    n({ "age": lt(30) })
])

Example 2: Filtering Nodes by Category

from graphistry import n, is_in

# Find nodes of type 'person' or 'company'
g_filtered = g.chain([
    n({ "type": is_in(["person", "company"]) })
])

Example 3: Filtering Edges with String Conditions

from graphistry import e_forward, contains

# Find edges where the relation contains 'friend'
g_filtered = g.chain([
    e_forward({ "relation": contains("friend") })
])

Example 4: Combining Multiple Predicates

from graphistry import n, eq, gt

# Find 'person' nodes with age greater than 18
g_filtered = g.chain([
    n({
        "type": eq("person"),
        "age": gt(18)
    })
])

Additional Notes

• Lambda Functions: You can use lambda functions for custom conditions.

  n({ "score": lambda x: (x > 50) & (x % 2 == 0) })
  

• Importing Operators: Remember to import the necessary functions.

  from graphistry import n, e_forward, gt, contains
  

• Combining Conditions: Use logical operators within lambdas for complex expressions.

  n({ "age": lambda x: (x > 18) & (x < 65) })
  

• Predicates Module: Operators are available in the graphistry.predicates module.