Function convertReturnClause

packages/graph/src/astToSteps.ts:2603–2945

* Convert RETURN clause to appropriate steps. * For mutation-only queries without RETURN, adds DrainStep to consume results.

(query: Query)

 * For mutation-only queries without RETURN, adds DrainStep to consume results.
 */
function convertReturnClause(query: Query): Step<any>[] {
  const steps: Step<any>[] = [];
  const returnClause = query.return;
  const groupByClause = query.groupBy;

  // If no RETURN clause (mutation-only query), add DrainStep
  // This ensures mutations execute (pipeline is consumed) but no results are returned
  if (!returnClause) {
    steps.push(new DrainStep({}));
    return steps;
  }

  // Check if we have any aggregate (using legacy format)
  const aggregateItems = returnClause.items.filter((item) => item.aggregate !== undefined);
  const aggregateItem = aggregateItems[0];

  // Check if we have any function calls (like labels(), type())
  // Using both legacy format and new expression format
  const functionItems = returnClause.items.filter(
    (item) => isLegacyFunctionExpression(item) !== null,
  );
  const functionItem = functionItems[0];
  const functionInfo = functionItem ? isLegacyFunctionExpression(functionItem) : null;

  // Check if we have any plain items (non-aggregate, non-function)
  // These could be plain variables, property access, or other expressions
  const plainItems = returnClause.items.filter(
    (item) => item.aggregate === undefined && isLegacyFunctionExpression(item) === null,
  );

  // If GROUP BY is present, use GroupByStep to handle mixed aggregates and functions
  if (groupByClause) {
    // Validate: non-aggregate RETURN items must appear in GROUP BY
    const nonAggregateItems = returnClause.items.filter((item) => item.aggregate === undefined);

    for (const returnItem of nonAggregateItems) {
      const matchesGroupBy = groupByClause.items.some((groupByItem) => {
        // Match by function (e.g., labels(n))
        if (returnItem.function && groupByItem.function) {
          return (
            returnItem.function === groupByItem.function &&
            returnItem.variable === groupByItem.variable
          );
        }
        // Match by property (e.g., n.name)
        if (returnItem.property && groupByItem.property) {
          return (
            returnItem.variable === groupByItem.variable &&
            returnItem.property === groupByItem.property
          );
        }
        // Match by variable (e.g., n)
        if (
          !returnItem.function &&
          !returnItem.property &&
          !groupByItem.function &&
          !groupByItem.property
        ) {