docs(gfql): document cypher-style row pipeline RETURN semantics

[lmeyerov]

Summary

• document GFQL row-pipeline primitives for Cypher-style MATCH ... RETURN workflows
• clarify where (same-path constraints) vs where_rows (row-table filtering)
• add explicit Cypher -> GFQL -> wire-protocol mapping examples for RETURN, ORDER BY, LIMIT, and GROUP BY
• add navigation/caveat updates in GFQL index docs

Dependency

• stacked on top of GFQL: Cypher-style row pipeline + parser-backed where_rows hardening #931 (feat/gfql-cypher-return-pipeline)

New/updated examples

Graph-pattern WHERE (same-path constraint)

from graphistry import n, e_forward, col, compare

g.gfql(
    [
        n({"type": "account"}, name="a"),
        e_forward(name="e"),
        n({"type": "user"}, name="c"),
    ],
    where=[compare(col("a", "owner_id"), "==", col("c", "owner_id"))],
)

Row-pipeline RETURN flow

from graphistry import n, e_forward, gt
from graphistry.compute import rows, where_rows, return_, order_by, limit

result = g.gfql([
    n({"type": "Person"}),
    e_forward({"type": "FOLLOWS"}),
    n({"type": "Person", "score": gt(0)}, name="p"),
    rows(table="nodes", source="p"),
    where_rows(expr="score >= 50"),
    return_(["id", "name", "score"]),
    order_by([("score", "desc"), ("name", "asc")]),
    limit(10),
])

Validation

• ruff check docs/source
• python -m py_compile graphistry/compute/gfql/row_pipeline_mixin.py
• PYTHONPATH=. pytest graphistry/tests/compute/gfql/test_expr_parser.py graphistry/tests/compute/gfql/test_row_pipeline_ops.py -q