diff --git a/source/atlas-search.txt b/source/atlas-search.txt index b099a5bd..b8b29306 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -4,5 +4,104 @@ Run an Atlas Search Query ========================= -.. TODO +.. facet:: + :name: genre + :values: reference +.. meta:: + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene + :description: Learn about how to use Atlas Search in the {+driver-long+}. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to +run :atlas:`Atlas Search ` queries on a collection. +Atlas Search enables you to perform full-text searches on collections +hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of the +search and which fields to index. + +Sample Data +~~~~~~~~~~~ + +The example in this guide uses the ``movies`` collection in the ``sample_mflix`` +database from the :atlas:`Atlas sample datasets `. To learn how to +create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Run an Atlas Search Query +------------------------- + +This section shows how to create an aggregation pipeline to run an +Atlas Search query on a collection. In your array of pipeline stages, +add the ``$search`` stage to specify the search criteria. Then, call +the ``Aggregate()`` method and pass your pipeline array as a parameter. + +.. tip:: + + To learn more about aggregation operations, see the :ref:`golang-aggregation` + guide. + +Before running an Atlas Search query, you must create an Atlas Search index +on your collection. To learn how to programmatically create an Atlas Search +index, see the :ref:`golang-atlas-search-indexes` section of the Indexes guide. + +Atlas Search Example +~~~~~~~~~~~~~~~~~~~~ + +This example runs an Atlas Search query by performing the +following actions: + +- Creates a ``$search`` stage that instructs the driver + to query for documents in which the ``title`` field contains + the word ``"Alabama"`` + +- Creates a ``$project`` stage that instructs the driver to + include the ``title`` field in the query results + +- Passes the pipeline stages to the ``Aggregate()`` method and + prints the results + +.. io-code-block:: + :copyable: + + .. input:: /includes/fundamentals/code-snippets/indexes/atlasSearch.go + :start-after: begin-atlas-search + :end-before: end-atlas-search + :language: go + :dedent: + + .. output:: + :language: console + :visible: false + + { + _id: new ObjectId('...'), + title: 'Alabama Moon' + } + { + _id: new ObjectId('...'), + title: 'Crazy in Alabama' + } + { + _id: new ObjectId('...'), + title: 'Sweet Home Alabama' + } + +Additional Information +---------------------- + +To learn more about Atlas Search, see :atlas:`Atlas Search ` +in the Atlas documentation. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``Aggregate()`` method, see the +`API documentation <{+api+}/mongo#Collection.Aggregate>`__. diff --git a/source/includes/fundamentals/code-snippets/indexes/atlasSearch.go b/source/includes/fundamentals/code-snippets/indexes/atlasSearch.go new file mode 100644 index 00000000..9e4c0d65 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/indexes/atlasSearch.go @@ -0,0 +1,56 @@ +package main + +import ( + "context" + "fmt" + "time" + + "go.mongodb.org/mongo-driver/v2/bson" + "go.mongodb.org/mongo-driver/v2/mongo" + "go.mongodb.org/mongo-driver/v2/mongo/options" +) + +func main() { + var err error + // connect to the Atlas cluster + ctx := context.Background() + // Retrieves your Atlas connection string + uri := os.Getenv("MONGODB_ATLAS_URI") + if uri == "" { + log.Fatal("MONGODB_ATLAS_URI environment variable is not set") + } + client, err := mongo.Connect(options.Client().SetTimeout(5 * time.Second).ApplyURI(uri)) + if err != nil { + panic(err) + } + defer client.Disconnect(ctx) + + // set namespace + collection := client.Database("sample_mflix").Collection("movies") + + // begin-atlas-search + // Defines the pipeline + searchStage := bson.D{{"$search", bson.D{ + {"text", bson.D{ + {"path", "title"}, + {"query", "Alabama"}, + }}, + }}} + projectStage := bson.D{{"$project", bson.D{{"title", 1}}}} + + // Runs the pipeline + cursor, err := collection.Aggregate(ctx, mongo.Pipeline{searchStage, projectStage}) + if err != nil { + panic(err) + } + + // Prints the results + var results []bson.D + if err = cursor.All(ctx, &results); err != nil { + panic(err) + } + for _, result := range results { + fmt.Println(result) + } + // end-atlas-search +}