Skip to content

feat(firestore): add raw execute options and move options #14259

Merged
bhshkh merged 2 commits intogoogleapis:mainfrom
bhshkh:fspq-execute-options
Mar 25, 2026
Merged

feat(firestore): add raw execute options and move options #14259
bhshkh merged 2 commits intogoogleapis:mainfrom
bhshkh:fspq-execute-options

Conversation

@bhshkh
Copy link
Copy Markdown
Contributor

@bhshkh bhshkh commented Mar 25, 2026

  1. Java and node Allow passing raw options to execute but Go does not. This PR adds the change.

  2. removal of WithExecuteOptions:
    The removal of WithExecuteOptions on the Pipeline builder and the shifting of its arguments directly into Execute(ctx, opts...) is a design pattern choice rooted heavily in idiomatic Go practices and separation of concerns.

    Here is a detailed breakdown of exactly why this change was made:

    1. Separation of Definition vs. Execution
      A Pipeline struct represents an immutable definition of a query. It builds a data structure that describes what data you want (e.g., Where(...), Select(...), Aggregate(...)).
      Execution options, on the other hand, describe how you want the backend to process that query (e.g., "return explain metrics", "use a specific index mode", "pass these raw backend flags").
      If WithExecuteOptions was left on the Pipeline, you would be coupling the query's definition with its execution metadata. By moving ExecuteOption to be a variadic argument on the Execute() method itself, you completely separate the two concerns.

    2. Reusability of the Pipeline
      Because the definition is now separated from the execution telemetry, a developer can build a pipeline once and execute it in multiple different ways without having to clone or mutate it:

      // 1. Define the Pipeline once
      myPipeline := client.Pipeline().Collection("books").Where("published", ">", 1990)
      
      // 2. Execute it normally in production
      res := myPipeline.Execute(ctx)
      
      // 3. Execute the exact same pipeline structure in a testing environment to analyze its performance
      explainRes := myPipeline.Execute(ctx, firestore.WithExplainMode(firestore.ExplainModeAnalyze))

      If WithExecuteOptions existed, the developer would have to fork the pipeline state to achieve this (myPipeline.WithExecuteOptions(...)).

    3. The Idiomatic "Functional Options" Pattern
      In Go, it is standard practice for functions that trigger a network request or a concrete action (Get, Set, Execute) to accept operational modifiers as trailing variadic arguments.
      If you look at the rest of the Google Cloud SDKs (or even standard library packages like grpc), you will see this pattern everywhere:

      • client.Collection("c").Doc("d").Get(ctx, firestore.opts...)
      • client.RunTransaction(ctx, f, firestore.opts...)
        Moving opts ...ExecuteOption directly into Execute(ctx context.Context, opts ...ExecuteOption) ensures maximum consistency with the rest of the Go SDK's API surface.

@bhshkh bhshkh requested review from a team as code owners March 25, 2026 17:28
@product-auto-label product-auto-label Bot added the api: firestore Issues related to the Firestore API. label Mar 25, 2026
@bhshkh bhshkh enabled auto-merge (squash) March 25, 2026 17:28
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the ability to specify raw execution options for Firestore pipelines using WithRawExecuteOptions, which are then passed directly to the backend. It also refactors the Pipeline.Execute method to accept ExecuteOptions directly, removing the separate WithExecuteOptions method. The Pipeline.copy() method was updated to handle deep copying of these new raw options. An integration test was added to verify the WithRawExecuteOptions functionality. A minor issue was noted regarding leftover debugging code in firestore/pipeline_result.go that prints marshaled requests and ignores potential errors.

Comment thread firestore/pipeline_result.go Outdated
@bhshkh bhshkh disabled auto-merge March 25, 2026 17:42
@bhshkh bhshkh merged commit d5a18a4 into googleapis:main Mar 25, 2026
10 checks passed
@bhshkh bhshkh deleted the fspq-execute-options branch March 25, 2026 18:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api: firestore Issues related to the Firestore API.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants