docs(gfql): Consolidated GFQL documentation improvements #719
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Consolidates work from multiple branches: - Comprehensive builtin_calls.rst from gfql-docs-v2 (1400+ lines) - All cypher_mapping.md improvements including GPU/CPU guidance - Updated translate.rst with algorithm variety - group_in_a_box_layout documentation - All chain→gfql API updates across documentation This creates a clean docs branch based on gfql-code-v2 with all improvements consolidated. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
6 tasks
BREAKING CHANGE: Fixed 59 incorrect chain() calls that should be gfql() This comprehensive audit identified and fixed critical documentation issues from the gfql-docs-clean-v2 to gfql-docs-clean-v3 consolidation: Restored Documentation (7 major sections): - "Sequencing Programs with Let" in 10min.rst - "Integration with PyData Ecosystem using Let and Call" in about.rst - Advanced Let() investigation example in about.rst - "Sequence Complex Analysis with Let" in overview.rst - "Using Let for Complex Remote Queries" in remote.rst (complete section) - "DAG Patterns with Let Bindings" in python_embedding.md (complete section) - "Graph Algorithms" section with APOC mapping in translate.rst Fixed API References: - 18 fixes in datetime_filtering.md - 16 fixes in python_embedding.md - 8 fixes in validation/fundamentals.rst - 5 fixes in validation/production.rst - 4 fixes in predicates/quick.rst - 2 fixes in language.md - 1 fix in 10min.rst Other Restorations: - GPU vs CPU Decision Guide with algorithm table in cypher_mapping.md - Call Operations notebook reference in notebooks/gfql.rst Impact: 678 insertions, 59 deletions across 13 files All Let() documentation critical for GFQL usage has been restored. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
Editorial improvements based on review feedback: 1. Added citations to Group-In-a-Box layout documentation: - Added reference to original paper (Rodrigues2011Group.pdf) - Added link to Graphistry blog post about GPU optimization - Noted that PyGraphistry's implementation is optimized for large graphs 2. Relocated wire_protocol_examples.md to proper location: - Moved from docs/source/gfql/ to docs/source/gfql/spec/ - Updated references in datetime_filtering.md and index.rst - Ensures all wire protocol docs are grouped in spec folder These changes improve documentation organization and provide proper academic attribution for the Group-In-a-Box algorithm. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Replace non-existent annotate_path=True with manual path tracking example - Add tip box explaining manual path tracking in GFQL using boolean attributes - Clarify Cypher's limitations with parallel pathfinding vs GFQL's wavefront execution - Emphasize GFQL's bulk vector joins and DataFrame integration benefits - Add comprehensive feature comparison table (GFQL, Cypher, GSQL, SQL, Pandas) - Enhance GPU-native algorithm integration explanation vs external APOC/GDS - Fix typo: "imepedance" → "impedance" 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Add clear value proposition: "Translate existing Cypher workloads to GPU-accelerated GFQL with minimal code changes"
- Restructure headers for parallel flow (Introduction → What Maps 1-to-1 → When You Need DataFrames → GFQL-Only Super-Powers → Translation Tables → Examples → Limits/Not-Supported → Best Practices)
- Remove marketing language ("rich", "massively", "built-in") and passive voice
- Use imperative voice in guides ("Apply gt() early to prune nodes")
- Convert GPU vs CPU decision guide to 2-column table format
- Delete unnecessary LLM Integration Guide section
- Split predicates table (basic predicates vs Collection/String Operations)
- Add Wire Protocol cross-reference link
- Clarify e_forward(hops=3) as "upper-bound only; lower bound = 1"
- Move plain equality to top of predicates table with "literal" marker
- Shorten WITH => Let code example for clarity
- Unify algorithm table headers as "GFQL Call (GPU)" and "GFQL Call (CPU)"
- Add OPTIONAL MATCH workaround hint ("simulate with left join on outer merge")
- Clarify hybrid approach uses "df.groupby/agg" specifically
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
- Replace ✅ with **Yes** for native support - Replace ❌ with **No** for not supported - Replace 🟡 with **Partial** for partial/manual support - Update legend to match new text-based indicators Fixes LaTeX build errors caused by Unicode emoji characters not being supported in LaTeX PDF generation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Add superscript references (1-5) to Partial and nuanced entries - Add detailed footnotes explaining: - Path return workarounds using name/path_id tagging - Optional match emulation via post-join left merges - Aggregations done outside GFQL using Pandas/cuDF - Procedural logic via Let() and embedded Python - Visualization differences between GFQL and Pandas - Update "Procedural logic" from "No" to "Partial" for GFQL to reflect Let() capabilities Provides clearer guidance on GFQL capabilities and workarounds for users comparing with other graph query languages. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Create comprehensive Loading Graph Data guide at docs/source/visualization/loading_graph_data.rst - Add sections for loading from DataFrames, CSV files, URLs, and GPU acceleration - Include tested examples with honeypot dataset - Add to Visualize section TOC after 10 Minutes tutorial - Document alternative constructors and next steps 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Update about.rst to reference loading guide in Basic Concepts - Update overview.rst to reference loading guide in Key GFQL Concepts - Update translate.rst with DataFrame-native explanation and loading guide reference - Update quick.rst with minimal reference to loading guide - Ensure consistent messaging about graph DataFrames across documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Add Minimal Graphs section for edges-only construction - Expand Binding Nodes and Edges with multiple patterns - Add Hypergraphs section with indirect/direct modes - Add GPU vs CPU DataFrames comparison and guidelines - Add Import from Other Systems (NetworkX, igraph, databases, Spark) - Add Export Graph Data section with pipeline examples - Include tested code examples for all patterns - Add external links to pandas I/O and RAPIDS benchmarks Addresses all 7 requirements: 1. Minimal graphs from pandas/CSV/Parquet 2. Node + edge binding patterns 3. Hypergraph documentation 4. GPU vs CPU guidance 5. Import adapters with links 6. Export patterns with examples 7. All examples tested and working 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Fix 16 incorrect ref() usages across 5 documentation files
- Change from incorrect ref('name').gfql([...]) to correct ref('name', [...])
- Update Let to lowercase let in imports and usage
- Ensure all ref() calls use the proper two-parameter syntax
The ref() function requires exactly 2 parameters:
1. name: string - the binding name to reference
2. chain: list - operations to apply (can be empty list)
Affected files:
- 10min.rst: 3 fixes
- about.rst: 2 fixes + Let→let
- overview.rst: 2 fixes + missing call import
- remote.rst: 6 fixes
- cypher_mapping.md: 3 fixes + Let→let
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 25, 2025
- Extract builtin_calls.rst from PR #719 (gfql-docs-clean-v3) - Document all 24 safelist methods with detailed parameters - Include working examples for each Call operation - Add schema effects documentation - Include algorithm categorization with external links - Add GPU vs CPU recommendations for each method - Update index.rst to include builtin_calls in TOC This critical documentation was missing from PR #745 and provides essential reference material for using GFQL Call operations.
lmeyerov
added a commit
that referenced
this pull request
Sep 25, 2025
…from #742) (#745) * feat(docs): add RST validation tooling for documentation Added comprehensive RST validation infrastructure to catch documentation syntax errors early in development and CI: - Created .rstcheck.cfg to configure RST validation, ignoring Sphinx-specific roles and directives while catching real syntax errors - Added bin/validate-docs.sh script for AI-friendly local validation during development (supports --changed flag for validating only modified files) - Added rstcheck[sphinx] to docs dependencies in setup.py - Integrated RST validation into docs Docker build process to fail early on syntax errors before attempting Sphinx build - Updated CLAUDE.md with documentation validation guidance for AI assistants This ensures documentation quality by catching RST syntax errors before they reach production, making it easier for both humans and AI assistants to maintain documentation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(ci): use setup.py docs extras for RST linting dependencies Changed lint-docs-rst job to install dependencies via setup.py's [docs] extras instead of installing rstcheck directly. This ensures: - Consistent dependency versions across all docs-related jobs - Single source of truth for documentation dependencies - Proper installation of all required docs tools, not just rstcheck 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor(ci): remove redundant lint-docs-rst job Removed the separate lint-docs-rst job since RST validation is already integrated into the test-docs job via the Docker build process. The validation happens automatically in build-docs.sh before Sphinx runs, making a separate job unnecessary. This simplifies the CI workflow while maintaining the same validation coverage through the existing docs build pipeline. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor(docs): move .rstcheck.cfg to docs/ directory Moved .rstcheck.cfg from project root to docs/ directory since it's documentation-specific configuration. Updated all references: - bin/validate-docs.sh now checks docs/.rstcheck.cfg first - Docker build copies from docs/.rstcheck.cfg - CLAUDE.md documentation updated with new path This keeps documentation-related configs organized in the docs/ directory. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor(docs): move validation guidance to ai/README.md Moved documentation validation instructions from CLAUDE.md to ai/README.md where they belong. CLAUDE.md remains a simple pointer file as intended. Added RST validation commands to the Essential Commands section in ai/README.md for proper discoverability by AI assistants. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor(docs): move validate-docs.sh to docs/ directory Moved validation script from bin/ to docs/ since it's documentation-specific tooling. Updated references in ai/README.md accordingly. This keeps all documentation-related tools and configs together in the docs/ directory for better organization. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(docs): expand rstcheck config to ignore all Sphinx-specific directives Added missing Sphinx-specific directives and roles to .rstcheck.cfg: - Added autodata directive (used in API docs) - Added py:class, py:meth, and other py: prefixed roles - Added include directive This fixes validation errors for API documentation files that use Sphinx autodoc features. All 161 RST files now pass validation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix: make validate-docs.sh work in both Docker and local contexts - Script now detects whether it's running in /docs (Docker) or project root - Adjusts config and source paths accordingly - Fixes 'Config path not found' error in CI * feat(gfql): Extract comprehensive GFQL implementation from PR #708 This commit extracts the massive GFQL implementation from PR #708 containing: CORE IMPLEMENTATION (19 new files): - AST classes: ASTLet, ASTRemoteGraph, ASTRef, ASTCall (700+ lines) - Let execution engine: chain_let.py (445 lines) - Call execution system: call_executor.py + call_safelist.py (500+ lines) - Validation framework: gfql_validation/ (650+ lines) - Comprehensive test suite: 10 new test files (3,000+ lines) UNIFIED API & DEPRECATIONS (11 modified files): - New methods: gfql(), gfql_remote(), gfql_remote_shape() - Deprecation warnings: chain() → gfql(), chain_remote() → gfql_remote() - Public API: Added let, remote, ref, call aliases - Type distribution: py.typed marker for mypy/pyright support MODIFIED NOTEBOOKS (CI-tested): - demos/gfql/gfql_remote.ipynb - demos/gfql/gfql_validation_fundamentals.ipynb - demos/more_examples/graphistry_features/hop_and_chain_graph_pattern_mining.ipynb CONFIGURATION: - CI: Updated workflows for validation and type checking - CHANGELOG: Added comprehensive feature documentation - Packaging: MANIFEST.in and setup.cfg updates This represents the complete GFQL v2 implementation with: - DAG patterns with Let bindings and dependency resolution - Safe method execution with call operations and safelist - Comprehensive validation framework with structured error reporting - Full backward compatibility with deprecation warnings - Extensive test coverage ensuring quality Supersedes incomplete PRs #715/#716 which missed 80%+ of this implementation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(ast): Resolve _get_child_validators type annotation compatibility - Change base class ASTSerializable._get_child_validators return type from List to Sequence - Update all implementing methods to return Sequence['ASTSerializable'] - Fixes mypy variance errors where implementations returned List[ASTPredicate] or List[ASTObject] - Sequence is covariant, allowing subtype returns while maintaining type safety Resolves python-lint-types CI failures in Python 3.10 and 3.11. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * feat(gfql): Add group_in_a_box_layout to Call safelist - Add group_in_a_box_layout to SAFELIST_V1 with full parameter validation - Support all parameters: partition_alg, layout_alg, positioning, colors, engine - Add comprehensive pytest validation tests - Verified parameter types match implementation signature * feat(gfql): Add GraphOperation type constraints for let() bindings Add strict type validation to ensure let() bindings only accept operations that produce Plottable objects, preventing invalid wavefront matchers. ## Core Changes ### GraphOperation Type Definition - Add `GraphOperation` union type for valid let() binding values - Includes: Plottable, Chain, ASTRef, ASTCall, ASTRemoteGraph, ASTLet - Excludes: bare ASTNode, ASTEdge (wavefront matchers need context) ### ASTLet Validation Enhancement - Add GraphOperation validation in ASTLet._validate_fields() - Clear error messages guide users to valid operation types - Support mixed JSON/native object construction with validate parameter ### Dict Convenience Auto-Wrapping - Auto-wrap ASTNode/ASTEdge in Chain when dict passed to gfql() - Preserves user convenience while enforcing type safety - Maintains backward compatibility for dict-based GFQL queries ### Public API Cleanup - Remove chain_let from public API (use gfql() instead) - Improve error handling in hop() and chain execution - Add defensive checks for DataFrame column consistency ## Testing - 110 tests pass (100% success rate for runnable tests) - 4 tests skipped (documented runtime execution issues) - Comprehensive test coverage for all GraphOperation types - End-to-end validation of type constraints and error handling ## Breaking Changes - let() now rejects bare n() and e() - wrap in Chain([n()]) instead - chain_let() removed from public API - use gfql() instead 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(chain): resolve edge binding inconsistency in chain() function Fixed critical bug where chain() left output graphs with inconsistent edge bindings when temporary 'index' column was added and removed during processing. **Root Cause**: - chain() added 'index' column if g._edge was None - After processing, 'index' column was dropped from DataFrame - But output graph still had _edge='index' pointing to non-existent column - Subsequent chain() calls failed with "Column 'index' not found" **Solution**: - Store original edge binding before modification - Restore original binding when creating output graph after dropping 'index' column - Ensures edge binding stays consistent with actual DataFrame columns **Impact**: - Fixes 4 previously skipped tests that relied on chaining chain() results - Enables proper ASTRef chain execution in chain_let DAGs - No regressions - all existing functionality preserved **Tests Fixed**: - test_node_edge_combination - test_dag_with_node_and_chainref - test_diamond_pattern_execution - test_parallel_independent_branches 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(types): Add type ignores for mixed type processing in GraphOperation The ASTLet constructor temporarily stores different types during JSON/native processing before validation. Added type ignores to suppress mypy errors while maintaining runtime type safety through validation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(lint): Fix flake8 errors with proper dynamic imports - Fix E261: Add proper spacing before inline comments - Fix W292: Add newline at end of graph_operation.py - Fix F402: Add noqa comment for legitimate dynamic Chain import - Keep original Chain name for dynamic imports (no renaming needed) The TYPE_CHECKING import is only for type hints and doesn't conflict with runtime dynamic imports used to avoid circular dependencies. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(lint): Fix unused imports in hop.py Removed unused imports: - typing.Any - pandas as pd - Engine from graphistry.Engine Also fixed line length for import statement. Note: hop.py has many other whitespace/formatting issues that need cleanup. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(lint): Fix critical lint issues for CI - Remove trailing whitespace in graph_operation.py - Remove unused pandas import from ast.py - Remove unused GFQLValidationError import - Fix line length for typing imports Note: Many other whitespace and unused predicate imports remain but these are pre-existing issues not introduced by our changes. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(lint): Fix actual lint failures in test files Fixed only the issues that actually fail CI (not ignored by lint.sh): - F841: Renamed unused variables with underscore prefix and noqa - W292: Added newline at end of test_graph_operation.py The previous commits fixing F401, W291, W293 were not necessary as these are ignored by bin/lint.sh, but they don't hurt either. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(types): Add type ignores for runtime attribute checks Fixed mypy errors where runtime hasattr() checks aren't recognized: - ast.py:790: to_json() call on objects that may not have it - validate_schema.py:44: chain attribute access on Union type Both cases already have proper runtime checks, just need type ignores. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(types): Add type ignore for GraphOperation in validate_chain_schema call The binding_value is a GraphOperation (which includes Plottable) but validate_chain_schema expects List[ASTObject]. The runtime code handles this correctly, just needs type ignore. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(test): Update call operation tests for GraphOperation constraints - Wrap ASTNode in Chain for DAG tests to comply with GraphOperation type requirements - Add skip conditions for group_in_a_box_layout tests when method not available on test objects - Tests now pass with proper GraphOperation validation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix(typing): Restore PEP 561 py.typed configuration accidentally removed The GFQL extraction commit (de45ae5) was based on PR #708 which predated PR #714's py.typed support. This accidentally reversed the typing configuration that was added just 2 days earlier. This commit restores: - MANIFEST.in: include graphistry/py.typed for source distributions - setup.cfg: package_data configuration for wheel distributions - CI validation: ensure py.typed is included in built wheels This ensures type checkers (mypy, pyright, PyCharm) can properly use PyGraphistry's type annotations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor(gfql): Replace duplicate gfql_validation with deprecation proxies (#746) * refactor(gfql): Replace duplicate gfql_validation with deprecation proxies - Remove duplicate validate.py and exceptions.py files - Replace with deprecation proxy __init__.py that forwards to gfql module - Maintains backwards compatibility for any external users - Shows clear deprecation warning explaining the duplication - All 15 public exports properly proxied: * ValidationIssue, Schema classes * validate_syntax, validate_schema, validate_query functions * extract_schema, extract_schema_from_dataframes functions * format_validation_errors, suggest_fixes functions * All GFQL exception classes This addresses the accidental duplication created during the July 28 code extraction where gfql_validation became a duplicate of gfql/validate. * fix(lint): Fix linting issues in deprecation proxy - Move imports before deprecation warning to avoid E402 errors - Add noqa: E402 comments for necessary late imports - Add missing newline at end of file (W292) * fix(validation): Remove type ignore and add handling for new AST types - Replace type: ignore with proper getattr() call for dynamic attribute access - Add else clause to handle new AST types (ASTLet, ASTRef, ASTCall, ASTRemoteGraph) - Document that new AST types use their own _validate_fields() methods - Schema validation at chain level is not applicable for new types since they don't directly filter on dataframe columns like ASTNode/ASTEdge This fixes the missing validation cases identified in the plan (Phase 4). * fix(tests): Fix floating point precision issues in ring layout tests - Replace exact equality checks with approximate comparisons - Use np.isclose() for radius calculations with rtol=1e-10 - Add tolerance for MIN_R_DEFAULT/MAX_R_DEFAULT comparisons - Fixes CI failures on test-minimal-python across all Python versions These tests were failing in CI with tiny floating point differences: - 499.99999999999994 != 500 - 99.99999999999999 < 100 The fix allows for appropriate floating point tolerance while maintaining test correctness. * fix(docs): Fix GFQL remote notebook syntax - Replace non-existent 'pipe' syntax with proper ASTRef JSON format - Change {'var': 'name'} to {'type': 'Ref', 'ref': 'name', 'chain': []} - Restructure let bindings to use correct GFQL AST JSON syntax - Ensure all examples can execute with current GFQL implementation The 'pipe' syntax never existed in the implementation - it was incorrect documentation. Now using the correct ASTRef JSON format that matches the actual AST classes. * docs: Update GFQL remote notebook to use clean Python API - Import ref, let, ASTCall from graphistry.compute.ast - Replace verbose JSON with clean Python API throughout - Show that chain_remote() accepts Python objects directly - Add comparison section showing JSON vs Python API - Fix incorrect 'call' syntax (was using 'method', should be 'function') The Python API is much cleaner: Before: {'type': 'Ref', 'ref': 'data', 'chain': [...]} After: ref('data', [...]) * docs: Add auto-generated API documentation files 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Add comprehensive builtin_calls reference documentation - Extract builtin_calls.rst from PR #719 (gfql-docs-clean-v3) - Document all 24 safelist methods with detailed parameters - Include working examples for each Call operation - Add schema effects documentation - Include algorithm categorization with external links - Add GPU vs CPU recommendations for each method - Update index.rst to include builtin_calls in TOC This critical documentation was missing from PR #745 and provides essential reference material for using GFQL Call operations. --------- Co-authored-by: Claude <[email protected]>
lmeyerov
commented
Sep 25, 2025
| @@ -0,0 +1,147 @@ | |||
| # GFQL Built-in Calls Documentation Audit Report | |||
lmeyerov
commented
Sep 25, 2025
| # GFQL Documentation Consolidation Audit Plan | ||
|
|
||
| ## Overview | ||
| Systematic audit to ensure no documentation was lost during consolidation from multiple branches into gfql-docs-clean-v3. |
3 tasks
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
- Enhanced cypher_mapping.md introduction with clearer structure - Added GFQL-Only Super-Powers section highlighting unique features - Improved section headers and organization - Added comment to edge patterns table about upper-bound only - Reordered predicates table with literal first - Added DataFrame-native explanation to translate.rst - Added reference to loading-graph-data guide These improvements make the documentation clearer and more comprehensive for users migrating from Cypher to GFQL. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
Added comprehensive documentation for Call operations including: - Safelist architecture and security model - Categories of allowed operations (analysis, transformation, layout, encoding) - Validation stages and error codes - Prevents arbitrary code execution From PR #719 improvements (Step 52 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
Added comprehensive documentation for DAG patterns including: - Let bindings for named graph operations - Ref for referencing bindings with additional operations - Complex DAG pattern examples - RemoteGraph for distributed computing - Call operations with Let bindings From PR #719 improvements (Step 53 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
- Add Call Operations and Security section to spec/language.md - Add DAG Patterns with Let Bindings to spec/python_embedding.md - Update wire_protocol.md with new operation types - Add Python vs GFQL Let comparison to overview.rst - Add Let, Call, RemoteGraph examples to quick.rst - Create comprehensive loading_graph_data.rst guide - Add Sequencing Programs with Let to 10min.rst Part 2 of PR #719 documentation improvements
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
* docs(gfql): Rename chain() to gfql() throughout documentation - Renamed all g.chain() references to g.gfql() - Renamed all g.chain_remote() references to g.gfql_remote() - Added migration notes to CHANGELOG.md - Updated method references in spec documentation - Preserved Chain class references (not method calls) - Manual inspection of each change for semantic correctness This change aligns with the deprecation of chain() methods in favor of the clearer gfql() naming convention. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Apply PR #719 improvements to cypher_mapping and translate - Enhanced cypher_mapping.md introduction with clearer structure - Added GFQL-Only Super-Powers section highlighting unique features - Improved section headers and organization - Added comment to edge patterns table about upper-bound only - Reordered predicates table with literal first - Added DataFrame-native explanation to translate.rst - Added reference to loading-graph-data guide These improvements make the documentation clearer and more comprehensive for users migrating from Cypher to GFQL. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Remove broken reference to loading-graph-data Removed the reference to :ref:`loading-graph-data` as the file doesn't exist yet. The DataFrame-native explanation remains to help users understand GFQL's approach. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
- Enhanced cypher_mapping.md introduction with clearer structure - Added GFQL-Only Super-Powers section highlighting unique features - Improved section headers and organization - Added comment to edge patterns table about upper-bound only - Reordered predicates table with literal first - Added DataFrame-native explanation to translate.rst - Added reference to loading-graph-data guide These improvements make the documentation clearer and more comprehensive for users migrating from Cypher to GFQL. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
Added comprehensive documentation for Call operations including: - Safelist architecture and security model - Categories of allowed operations (analysis, transformation, layout, encoding) - Validation stages and error codes - Prevents arbitrary code execution From PR #719 improvements (Step 52 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
Added comprehensive documentation for DAG patterns including: - Let bindings for named graph operations - Ref for referencing bindings with additional operations - Complex DAG pattern examples - RemoteGraph for distributed computing - Call operations with Let bindings From PR #719 improvements (Step 53 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
- Add Call Operations and Security section to spec/language.md - Add DAG Patterns with Let Bindings to spec/python_embedding.md - Update wire_protocol.md with new operation types - Add Python vs GFQL Let comparison to overview.rst - Add Let, Call, RemoteGraph examples to quick.rst - Create comprehensive loading_graph_data.rst guide - Add Sequencing Programs with Let to 10min.rst Part 2 of PR #719 documentation improvements
lmeyerov
added a commit
that referenced
this pull request
Sep 26, 2025
…ments) (#750) * docs(gfql): Apply PR #719 improvements to cypher_mapping and translate - Enhanced cypher_mapping.md introduction with clearer structure - Added GFQL-Only Super-Powers section highlighting unique features - Improved section headers and organization - Added comment to edge patterns table about upper-bound only - Reordered predicates table with literal first - Added DataFrame-native explanation to translate.rst - Added reference to loading-graph-data guide These improvements make the documentation clearer and more comprehensive for users migrating from Cypher to GFQL. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Remove broken reference to loading-graph-data Removed the reference to :ref:`loading-graph-data` as the file doesn't exist yet. The DataFrame-native explanation remains to help users understand GFQL's approach. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Add Call Operations and Security section to language spec Added comprehensive documentation for Call operations including: - Safelist architecture and security model - Categories of allowed operations (analysis, transformation, layout, encoding) - Validation stages and error codes - Prevents arbitrary code execution From PR #719 improvements (Step 52 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Add Let/Ref/RemoteGraph documentation to python_embedding Added comprehensive documentation for DAG patterns including: - Let bindings for named graph operations - Ref for referencing bindings with additional operations - Complex DAG pattern examples - RemoteGraph for distributed computing - Call operations with Let bindings From PR #719 improvements (Step 53 of plan) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs(gfql): Add Let/Call/RemoteGraph documentation and loading guide - Add Call Operations and Security section to spec/language.md - Add DAG Patterns with Let Bindings to spec/python_embedding.md - Update wire_protocol.md with new operation types - Add Python vs GFQL Let comparison to overview.rst - Add Let, Call, RemoteGraph examples to quick.rst - Create comprehensive loading_graph_data.rst guide - Add Sequencing Programs with Let to 10min.rst Part 2 of PR #719 documentation improvements * docs(gfql): Fix Let bindings description in overview.rst - Remove incorrect claim about 'single-pass execution' - Clarify that Let creates named subgraphs/operations like variables - Emphasize DAG dependency management and composability - Maintain focus on GPU acceleration benefits * docs(gfql): Fix Let examples and improve Call description - Fix invalid Let examples that used bare matchers (now use Chain wrapper) - Add note that Chain wrapper is currently required (will be fixed) - Improve Call Operations description to be clearer about graph algorithms - Remove invalid example with ref() inside ref() chain * docs(gfql): Fix RemoteGraph→remote naming consistency All GFQL operations use lowercase aliases: - let() not Let() - ref() not Ref() - call() not Call() - remote() not RemoteGraph() Fixed documentation to use correct lowercase 'remote' alias --------- Co-authored-by: Claude <[email protected]>
2 tasks
Contributor
Author
|
Closing as the documentation updates are now handled in PR #752 (fix/notebook-gfql-renames) which updates notebooks to use gfql() instead of chain(). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR consolidates all GFQL documentation improvements from multiple branches into a clean stack:
Changes Consolidated
From gfql-docs-v2:
From gfql-docs-combined:
API Updates:
Key Documentation Improvements
builtin_calls.rst: Complete reference for all Call operations with:
cypher_mapping.md: Enhanced with:
translate.rst: Updated examples showing:
Integration: Added GFQL examples to ML/AI combo sections
Testing
🤖 Generated with Claude Code