feat(firestore): Implement Search pipeline stage and related expressions

[bhshkh]

Summary
This PR implements the search pipeline stage and its associated expressions in the Go Firestore SDK, providing parity with the Java (googleapis/java-firestore#2346) and Node.js (googleapis/google-cloud-node#7824) SDKs for full-text and geospatial search capabilities within Firestore Pipelines.

Key Changes

• Search Pipeline Stage:
  • Implemented the Search stage in Pipeline with a functional options pattern.
  • Introduced WithSearchQuery, WithSearchSort, WithSearchAddFields, and WithSearchRetrievalDepth options.
  • Ensured protobuf encoding places the query within the Options map (not Args) to align with backend requirements and the Java SDK implementation.
• Search Expressions:
  • Implemented DocumentMatches(query string) and Matches(field, query string) for full-text search.
  • Implemented GeoDistance(field, location) for geospatial distance calculations.
  • Implemented Score() to retrieve the search topicality score.
  • Implemented Snippet(field, query) for highlighted search result snippets.
• Fluent API:
  • Added GeoDistance(location), Matches(query), and Snippet(query) methods to the Expression interface to support fluent chaining (e.g., FieldOf("location").GeoDistance(loc)).
• Testing:
  • Added comprehensive unit tests in pipeline_test.go and pipeline_function_test.go.
  • Verified backend request structure consistency via JSON dump comparisons.

Usage Example

pipeline := client.Pipeline().
    Collection("restaurants").
    Search(
        WithSearchQuery(DocumentMatches("waffles OR pancakes")),
        WithSearchSort(Descending(Score())),
        WithSearchAddFields(Snippet("menu", "waffles").As("highlight")),
    )

[gemini-code-assist]

Code Review

This pull request adds the Search pipeline stage and associated functions like DocumentMatches, GeoDistance, and Snippet to the Firestore SDK. The changes include protobuf mapping, unit tests, and integration tests. Feedback focuses on correcting documentation examples that used incorrect method signatures and recommending the use of the idiomatic GeoPoint type instead of internal proto types for geospatial coordinates. A simplification of the protobuf conversion logic in the search stage was also suggested.

[MarkDuckworth]

Snippet will not be supported at launch. Are you seeing that it is supported in your testing?

[daniel-sanche]

Are Snippet/Matches working? I thought they were pushed to after Next

[bhshkh]

No. Removed them

[daniel-sanche]

IIRC search has some other options available (limit, select, query_enhancement, language_code). Have you checked if they are still in scope?

[bhshkh]

Adding these does not return any errors while testing. Saw only one limitation that select supports only score.

@MarkDuckworth, are they still in scope?

[MarkDuckworth]

The only features exposed in the (java, node, iOS, Android, and Web) SDKs for the launch are:

Search stage:

• query
• sort
• addFields

Expressions:

• documentMatches(query)
• field(name).geoDistance(point) / geoDistance(field, point)
• score()

My understanding is that the backend now also supports:

• offset
• limit
• languageCode
• retrievalDepth

These will be a fast follow for the Java, Node, iOS, Android, and Web SDKs, so IMO it's okay to include them in the initial release for Go and Python.

[bhshkh]

Snippet will not be supported at launch. Are you seeing that it is supported in your testing?

TEsts were missing for those. After adding, found out that they are not supported. Removed them.