usage-examples.txt

.. _golang-usage-examples:

==============
Usage Examples
==============

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: read, write, example, code example

.. toctree::

   Find Operations </usage-examples/find-operations>
   Write Operations </usage-examples/write-operations>
   Bulk Operations </usage-examples/bulkWrite>
   Monitor Data Changes Example </usage-examples/changestream>
   Count Documents Method Example </usage-examples/count>
   Distinct Field Values </usage-examples/distinct>
   Run a Command </usage-examples/command>
   Use Struct Tags </usage-examples/struct-tagging>

Overview
--------

Usage examples provide convenient starting points for popular MongoDB
operations. Each example provides the following:

- A full Go program that you can run in your own environment
- The expected result after running the program

How to Use the Usage Examples
-----------------------------

These examples use the :atlas:`sample datasets </sample-data>` provided by
Atlas. You can load them into your database on the free tier of MongoDB
Atlas by following the :atlas:`Get Started with Atlas Guide
</getting-started/#atlas-getting-started>` or you can
:guides:`import the sample dataset into a local MongoDB instance
</server/import/>`.

Once you import the dataset, you can copy and paste a usage
example into your development environment of choice. You can follow the
:ref:`Quick Start <golang-quickstart>` to learn more about getting
started with the {+driver-long+}.

Connection String
~~~~~~~~~~~~~~~~~

Follow the :ref:`"Connect to your Cluster" <golang-connect-to-your-cluster>`
step to find the
:manual:`connection string </reference/connection-string/>` to define your
``MONGODB_URI`` environment variable to run the usage examples. If your
instance uses :manual:`SCRAM authentication </core/security-scram/>`,
you can replace ``<user>`` with your username, ``<password>`` with your
password, and ``<cluster-url>`` with the URL or IP address of your instance.

To learn more about connecting to your MongoDB instance, see :ref:`golang-connection-guide`.

Environment Variable
~~~~~~~~~~~~~~~~~~~~

To connect the example to your MongoDB instance, you must :ref:`define
an environment variable <golang-usage-examples-env-variable>` by using
your connection string.

.. code-block:: go

   uri := os.Getenv("MONGODB_URI")

.. _golang-usage-examples-env-variable:


You can use `GoDotEnv <https://github.com/joho/godotenv>`__ to define
your environment variable.

Add the following application configuration in your ``.env`` file at the
root of your project, replacing the placeholders with the values for your
deployment's connection string. To learn more, see the
`GoDotEnv documentation <https://github.com/joho/godotenv#usage>`__.

.. code-block::

   MONGODB_URI=mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority

Examples
--------

You can find usage examples for the following tasks:

- :ref:`golang-find-one`
- :ref:`golang-find-multiple`
- :ref:`golang-insert-one`
- :ref:`golang-insert-many`
- :ref:`golang-update-one`
- :ref:`golang-update-many`
- :ref:`golang-replace`
- :ref:`golang-delete-one`
- :ref:`golang-delete-many`
- :ref:`golang-bulk-ops-usage-example`
- :ref:`golang-watch`
- :ref:`golang-count-usage-example`
- :ref:`golang-distinct-usage-example`
- :ref:`golang-run-command-usage-example`
- :ref:`golang-struct-tags-usage-example`