graphistry.compute.gfql package

graphistry.compute.gfql package#

Submodules#

graphistry.compute.gfql.exceptions module#

GFQL-specific exceptions for validation and error handling.

exception graphistry.compute.gfql.exceptions.GFQLColumnNotFoundError(column, table, available_columns)#

Bases: GFQLSchemaError

Raised when a referenced column doesn’t exist in the schema.

Parameters:

  • column (str)

  • table (str)

  • available_columns (list)

exception graphistry.compute.gfql.exceptions.GFQLException(message, context=None)#

Bases: Exception

Base exception for all GFQL-related errors.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.exceptions.GFQLSchemaError(message, context=None)#

Bases: GFQLValidationError

Raised when GFQL query references non-existent columns or has type mismatches.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.exceptions.GFQLSemanticError(message, context=None)#

Bases: GFQLValidationError

Raised when GFQL query is syntactically valid but semantically incorrect.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.exceptions.GFQLSyntaxError(message, context=None)#

Bases: GFQLValidationError

Raised when GFQL query has invalid syntax.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.exceptions.GFQLTypeError(column, column_type, predicate, expected_type)#

Bases: GFQLSchemaError

Raised when a predicate is applied to incompatible column type.

Parameters:

  • column (str)

  • column_type (str)

  • predicate (str)

  • expected_type (str)

exception graphistry.compute.gfql.exceptions.GFQLValidationError(message, context=None)#

Bases: GFQLException, ValueError

Base validation error. Inherits from ValueError for backwards compatibility.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

graphistry.compute.gfql.validate module#

GFQL query validation utilities for syntax and schema checking.

Deprecated since version 0.34.0: This module is deprecated. GFQL now has built-in validation. See /gfql/validation_migration_guide for migration instructions.

Instead of:

from graphistry.compute.gfql.validate import validate_syntax
issues = validate_syntax(query)

Use:

from graphistry.compute.chain import Chain
try:
    chain = Chain(query)  # Automatic validation
except GFQLValidationError as e:
    print(f"[{e.code}] {e.message}")
class graphistry.compute.gfql.validate.Schema(node_columns=None, edge_columns=None)#

Bases: object

Represents the schema of node and edge dataframes.

Parameters:

  • node_columns (Dict[str, str] | None)

  • edge_columns (Dict[str, str] | None)

class graphistry.compute.gfql.validate.ValidationIssue(level, message, operation_index=None, field=None, suggestion=None, error_type=None)#

Bases: object

Represents a validation issue (error or warning).

Parameters:

  • level (str)

  • message (str)

  • operation_index (int | None)

  • field (str | None)

  • suggestion (str | None)

  • error_type (str | None)

to_dict()#

Convert to dictionary for JSON serialization.

Return type:

Dict[str, Any]

graphistry.compute.gfql.validate.extract_schema(g)#

Extract schema from a Plottable object.

Args:

g: Plottable object with node/edge data

Returns:

Schema object

Parameters:

g (Plottable)

Return type:

Schema

graphistry.compute.gfql.validate.extract_schema_from_dataframes(nodes_df=None, edges_df=None)#

Extract schema from pandas DataFrames.

Args:

nodes_df: Optional node dataframe edges_df: Optional edge dataframe

Returns:

Schema object with column names and types

Parameters:

  • nodes_df (DataFrame | None)

  • edges_df (DataFrame | None)

Return type:

Schema

graphistry.compute.gfql.validate.format_validation_errors(issues)#

Format validation errors for human/LLM consumption.

Args:

issues: List of validation issues

Returns:

Formatted error string

Parameters:

issues (List[ValidationIssue])

Return type:

str

graphistry.compute.gfql.validate.suggest_fixes(chain, issues)#

Generate fix suggestions for validation issues.

Args:

chain: The problematic chain issues: Validation issues found

Returns:

List of suggested fixes

Parameters:
Return type:

List[str]

graphistry.compute.gfql.validate.validate_query(chain, nodes_df=None, edges_df=None)#

Combined syntax and schema validation.

Args:

chain: GFQL chain or list of operations nodes_df: Optional node dataframe for schema validation edges_df: Optional edge dataframe for schema validation

Returns:

List of validation issues

Parameters:

  • chain (Chain | List)

  • nodes_df (DataFrame | None)

  • edges_df (DataFrame | None)

Return type:

List[ValidationIssue]

graphistry.compute.gfql.validate.validate_schema(chain, schema)#

Validate query against data schema.

Args:

chain: GFQL chain or list of operations schema: Schema object with column information

Returns:

List of validation issues

Parameters:
Return type:

List[ValidationIssue]

graphistry.compute.gfql.validate.validate_syntax(chain)#

Validate GFQL query syntax without requiring data.

Args:

chain: GFQL chain or list of operations

Returns:

List of validation issues (errors and warnings)

Parameters:

chain (Chain | List)

Return type:

List[ValidationIssue]

Module contents#

GFQL validation and related utilities.

exception graphistry.compute.gfql.GFQLColumnNotFoundError(column, table, available_columns)#

Bases: GFQLSchemaError

Raised when a referenced column doesn’t exist in the schema.

Parameters:

  • column (str)

  • table (str)

  • available_columns (list)

exception graphistry.compute.gfql.GFQLException(message, context=None)#

Bases: Exception

Base exception for all GFQL-related errors.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.GFQLSchemaError(message, context=None)#

Bases: GFQLValidationError

Raised when GFQL query references non-existent columns or has type mismatches.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.GFQLSyntaxError(message, context=None)#

Bases: GFQLValidationError

Raised when GFQL query has invalid syntax.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

exception graphistry.compute.gfql.GFQLTypeError(column, column_type, predicate, expected_type)#

Bases: GFQLSchemaError

Raised when a predicate is applied to incompatible column type.

Parameters:

  • column (str)

  • column_type (str)

  • predicate (str)

  • expected_type (str)

exception graphistry.compute.gfql.GFQLValidationError(message, context=None)#

Bases: GFQLException, ValueError

Base validation error. Inherits from ValueError for backwards compatibility.

Parameters:

  • message (str)

  • context (Dict[str, Any] | None)

class graphistry.compute.gfql.Schema(node_columns=None, edge_columns=None)#

Bases: object

Represents the schema of node and edge dataframes.

Parameters:

  • node_columns (Dict[str, str] | None)

  • edge_columns (Dict[str, str] | None)

class graphistry.compute.gfql.ValidationIssue(level, message, operation_index=None, field=None, suggestion=None, error_type=None)#

Bases: object

Represents a validation issue (error or warning).

Parameters:

  • level (str)

  • message (str)

  • operation_index (int | None)

  • field (str | None)

  • suggestion (str | None)

  • error_type (str | None)

to_dict()#

Convert to dictionary for JSON serialization.

Return type:

Dict[str, Any]

graphistry.compute.gfql.extract_schema(g)#

Extract schema from a Plottable object.

Args:

g: Plottable object with node/edge data

Returns:

Schema object

Parameters:

g (Plottable)

Return type:

Schema

graphistry.compute.gfql.extract_schema_from_dataframes(nodes_df=None, edges_df=None)#

Extract schema from pandas DataFrames.

Args:

nodes_df: Optional node dataframe edges_df: Optional edge dataframe

Returns:

Schema object with column names and types

Parameters:

  • nodes_df (DataFrame | None)

  • edges_df (DataFrame | None)

Return type:

Schema

graphistry.compute.gfql.format_validation_errors(issues)#

Format validation errors for human/LLM consumption.

Args:

issues: List of validation issues

Returns:

Formatted error string

Parameters:

issues (List[ValidationIssue])

Return type:

str

graphistry.compute.gfql.suggest_fixes(chain, issues)#

Generate fix suggestions for validation issues.

Args:

chain: The problematic chain issues: Validation issues found

Returns:

List of suggested fixes

Parameters:
Return type:

List[str]

graphistry.compute.gfql.validate_query(chain, nodes_df=None, edges_df=None)#

Combined syntax and schema validation.

Args:

chain: GFQL chain or list of operations nodes_df: Optional node dataframe for schema validation edges_df: Optional edge dataframe for schema validation

Returns:

List of validation issues

Parameters:

  • chain (Chain | List)

  • nodes_df (DataFrame | None)

  • edges_df (DataFrame | None)

Return type:

List[ValidationIssue]

graphistry.compute.gfql.validate_schema(chain, schema)#

Validate query against data schema.

Args:

chain: GFQL chain or list of operations schema: Schema object with column information

Returns:

List of validation issues

Parameters:
Return type:

List[ValidationIssue]

graphistry.compute.gfql.validate_syntax(chain)#

Validate GFQL query syntax without requiring data.

Args:

chain: GFQL chain or list of operations

Returns:

List of validation issues (errors and warnings)

Parameters:

chain (Chain | List)

Return type:

List[ValidationIssue]