DOCSP-28090 user-roles-in-aggregations (#3235)

jason-price-mongodb · jason-price-mongodb · web-flow · commit 476e78f783ee · 2023-06-22T09:28:59.000-04:00
* DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations * DOCSP-28090-user-roles-in-aggregations --------- Co-authored-by: jason-price-mongodb <jshfjghsdfgjsdjh@aolsdjfhkjsdhfkjsdf.com>
diff --git a/source/core/views/create-view.txt b/source/core/views/create-view.txt
@@ -76,11 +76,11 @@ Some operations are not available with views:
 
 For more information, see :ref:`views-supported-operations`.
 
-Example
--------
+Examples
+--------
 
-This example populates a collection with student data and creates a view
-to query the data.
+The first example populates a collection with student data and creates a
+view to query the data.
 
 Populate the Collection
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -202,6 +202,129 @@ lowercase letters.
      { sID: 17301, name: 'harley', year: 6, score: 3.1 }
    ]
 
+.. _create-view-user-roles-system-variable-example:
+
+Retrieve Documents for Roles Granted to the Current User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/user-roles-system-variable-introduction.rst
+
+Perform the following steps to create a view and retrieve the documents
+accessible to ``John``:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Create the view
+
+      .. include:: /includes/user-roles-system-variable-example-description-start.rst
+
+      Run:
+
+      .. code-block:: javascript
+         :emphasize-lines: 7
+
+         db.createView(
+            "budgetView", "budget",
+            [ {
+               $match: {
+                  $expr: {
+                     $not: {
+                        $eq: [ { $setIntersection: [ "$allowedRoles", "$$USER_ROLES.role" ] }, [] ]
+                     }
+                  }
+               }
+            } ]
+         )
+
+      If you cannot create the view, ensure you log in as a user with
+      the privilege to create a view.
+
+      .. include:: /includes/user-roles-system-variable-example-description.rst
+
+   .. step:: Log in as John
+
+      .. include:: /includes/user-roles-system-variable-example-login-john.rst
+
+   .. step:: Retrieve the documents
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.budgetView.find()
+
+   .. step:: Examine the documents
+
+      .. include:: /includes/user-roles-system-variable-example-output-john.rst
+
+Perform the following steps to retrieve the documents accessible to
+Jane:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``Jane``
+
+      .. include:: /includes/user-roles-system-variable-example-login-jane.rst
+
+   .. step:: Retrieve the documents
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.budgetView.find()
+
+   .. step:: Examine the documents
+
+      .. include:: /includes/user-roles-system-variable-example-output-jane.rst
+
+Roles with the Same Name in Multiple Databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Multiple databases can have roles with the same name. If you create a
+view and reference a specific role in the view, you should either
+specify both the ``db`` database name field and the ``role`` field, or
+specify the ``_id`` field that contains the database name and the role.
+
+The following example returns the roles assigned to ``Jane``, who has
+roles with different names. The example returns the ``_id``, ``role``,
+and ``db`` database name:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``Jane``
+
+      .. include:: /includes/user-roles-system-variable-example-login-jane.rst
+
+   .. step:: Retrieve the documents
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.budget.findOne( {}, { myRoles: "$$USER_ROLES" } )
+
+   .. step:: Examine the documents
+
+      Example output, which shows the ``_id``, ``role``, and ``db``
+      database name in the ``myRoles`` array:
+
+      .. code-block:: javascript
+         :copyable: false
+         :emphasize-lines: 3-6
+
+         {
+            _id: 0,
+            myRoles: [
+               { _id: 'test.Operations', role: 'Operations', db: 'test' },
+               { _id: 'test.Sales', role: 'Sales', db: 'test' },
+               { _id: 'test.read', role: 'read', db: 'test' }
+            ]
+         }
+
 Behavior
 --------
 
diff --git a/source/includes/user-roles-system-variable-example-description-start.rst b/source/includes/user-roles-system-variable-example-description-start.rst
@@ -0,0 +1,3 @@
+To use a system variable, add ``$$`` to the start of the variable name.
+The ``USER_ROLES`` system variable is specified as ``$$USER_ROLES`` as
+shown in the following example.
diff --git a/source/includes/user-roles-system-variable-example-description.rst b/source/includes/user-roles-system-variable-example-description.rst
@@ -0,0 +1,6 @@
+The previous example returns the documents from the ``budget``
+collection that match at least one of the roles that the user who runs
+the example has. To do that, the example uses
+:expression:`$setIntersection` to return documents where the
+intersection between the ``budget`` document ``allowedRoles`` field and
+the set of user roles from ``$$USER_ROLES`` is not empty.
diff --git a/source/includes/user-roles-system-variable-example-find.rst b/source/includes/user-roles-system-variable-example-find.rst
@@ -0,0 +1,12 @@
+Run:
+
+.. code-block:: javascript
+   :emphasize-lines: 4
+
+   db.budget.find( {
+      $expr: {
+         $not: {
+            $eq: [ { $setIntersection: [ "$allowedRoles", "$$USER_ROLES.role" ] }, [] ]
+         }
+      }
+   } )
diff --git a/source/includes/user-roles-system-variable-example-login-jane.rst b/source/includes/user-roles-system-variable-example-login-jane.rst
@@ -0,0 +1,5 @@
+Run:
+
+.. code-block:: javascript
+
+   db.auth( "Jane", "je009" )
diff --git a/source/includes/user-roles-system-variable-example-login-john.rst b/source/includes/user-roles-system-variable-example-login-john.rst
@@ -0,0 +1,5 @@
+Run:
+
+.. code-block:: javascript
+
+   db.auth( "John", "jn008" )
diff --git a/source/includes/user-roles-system-variable-example-output-jane.rst b/source/includes/user-roles-system-variable-example-output-jane.rst
@@ -0,0 +1,22 @@
+``Jane`` has the ``Sales`` and ``Operations`` roles, and sees these
+documents:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      {
+         _id: 1,
+         allowedRoles: [ 'Sales' ],
+         comment: 'For sales team',
+         yearlyBudget: 17000,
+         salesEventsBudget: 1000
+      },
+      {
+         _id: 2,
+         allowedRoles: [ 'Operations' ],
+         comment: 'For operations team',
+         yearlyBudget: 19000,
+         cloudBudget: 12000
+      }
+   ]
diff --git a/source/includes/user-roles-system-variable-example-output-john.rst b/source/includes/user-roles-system-variable-example-output-john.rst
@@ -0,0 +1,27 @@
+``John`` has the ``Marketing``, ``Operations``, and ``Development``
+roles, and sees these documents:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      {
+         _id: 0,
+         allowedRoles: [ 'Marketing' ],
+         comment: 'For marketing team',
+         yearlyBudget: 15000
+      },
+      {
+         _id: 2,
+         allowedRoles: [ 'Operations' ],
+         comment: 'For operations team',
+         yearlyBudget: 19000,
+         cloudBudget: 12000
+      },
+      {
+         _id: 3,
+         allowedRoles: [ 'Development' ],
+         comment: 'For development team',
+         yearlyBudget: 27000
+      }
+   ]
diff --git a/source/includes/user-roles-system-variable-example-pipeline.rst b/source/includes/user-roles-system-variable-example-pipeline.rst
@@ -0,0 +1,14 @@
+Run:
+
+.. code-block:: javascript
+   :emphasize-lines: 5
+
+   db.budget.aggregate( [ {
+      $match: {
+         $expr: {
+            $not: {
+               $eq: [ { $setIntersection: [ "$allowedRoles", "$$USER_ROLES.role" ] }, [] ]
+            }
+         }
+      }
+   } ] )
diff --git a/source/includes/user-roles-system-variable-examples-list.rst b/source/includes/user-roles-system-variable-examples-list.rst
@@ -0,0 +1,4 @@
+For examples that include ``USER_ROLES``, see the :ref:`find example
+<find-user-roles-system-variable-example>`, :ref:`aggregation example
+<setIntersection-user-roles-system-variable-example>`, and the
+:ref:`view example <create-view-user-roles-system-variable-example>`.
diff --git a/source/includes/user-roles-system-variable-introduction.rst b/source/includes/user-roles-system-variable-introduction.rst
@@ -0,0 +1,102 @@
+Starting in MongoDB 7.0, you can use the new :variable:`USER_ROLES`
+system variable to return user :ref:`roles <roles>`.
+
+The scenario in this section shows users with various roles who have
+limited access to documents in a collection containing budget
+information.
+
+The scenario shows one possible use of ``USER_ROLES``. The ``budget``
+collection contains documents with a field named ``allowedRoles``. As
+you'll see in the following scenario, you can write queries that compare
+the user roles found in the ``allowedRoles`` field with the roles
+returned by the ``USER_ROLES`` system variable.
+
+.. note::
+
+   Another possible ``USER_ROLES`` example scenario: you could store
+   medical diagnosis and insurance data in a collection. You could then
+   use ``USER_ROLES`` in an aggregation pipeline to transform the data
+   so that the diagnosis data can only be viewed by a user with a
+   provider role and the insurance data can only be viewed by a user
+   with a billing role. You don't have to include those user roles in
+   document fields to use ``USER_ROLES``.
+
+For the budget scenario in this section, perform the following steps to
+create the required roles, users, and ``budget`` collection:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Create the roles
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.createRole( { role: "Marketing", roles: [], privileges: [] } )
+         db.createRole( { role: "Sales", roles: [], privileges: [] } )
+         db.createRole( { role: "Development", roles: [], privileges: [] } )
+         db.createRole( { role: "Operations", roles: [], privileges: [] } )
+
+   .. step:: Create the users
+
+      Create users named ``John`` and ``Jane`` with the required roles.
+      Replace the ``test`` database with your database name.
+
+      .. code-block:: javascript
+
+         db.createUser( {
+            user: "John",
+            pwd: "jn008",
+            roles: [
+               { role: "Marketing", db: "test" },
+               { role: "Development", db: "test" },
+               { role: "Operations", db: "test" },
+               { role: "read", db: "test" }
+            ]
+         } )
+
+         db.createUser( {
+            user: "Jane",
+            pwd: "je009",
+            roles: [
+               { role: "Sales", db: "test" },
+               { role: "Operations", db: "test" },
+               { role: "read", db: "test" }
+            ]
+         } )
+
+   .. step:: Create the collection
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.budget.insertMany( [
+            {
+               _id: 0,
+               allowedRoles: [ "Marketing" ],
+               comment: "For marketing team",
+               yearlyBudget: 15000
+            }, 
+            {
+               _id: 1,
+               allowedRoles: [ "Sales" ],
+               comment: "For sales team",
+               yearlyBudget: 17000,
+               salesEventsBudget: 1000
+            },
+            {
+               _id: 2,
+               allowedRoles: [ "Operations" ],
+               comment: "For operations team",
+               yearlyBudget: 19000,
+               cloudBudget: 12000
+            },
+            {
+               _id: 3,
+               allowedRoles: [ "Development" ],
+               comment: "For development team",
+               yearlyBudget: 27000
+            }
+         ] )
diff --git a/source/meta/aggregation-quick-reference.txt b/source/meta/aggregation-quick-reference.txt
@@ -107,7 +107,7 @@ prefix the variable name with ``$$``. For example:
 
    * - Variable
    
-     - Access via ``$$``
+     - Access using ``$$``
      
      - Brief Description
      
@@ -165,6 +165,16 @@ prefix the variable name with ``$$``. For example:
      
      - One of the allowed results of a :pipeline:`$redact` expression.
 
+   * - :variable:`USER_ROLES`
+   
+     - ``$$USER_ROLES``
+     
+     - Returns the :ref:`roles <roles>` assigned to the current user.
+
+       .. include:: /includes/user-roles-system-variable-examples-list.rst
+
+       .. versionadded:: 7.0
+
 For a more detailed description of these variables, see :ref:`system
 variables <agg-system-variables>`.
 
diff --git a/source/reference/aggregation-variables.txt b/source/reference/aggregation-variables.txt
@@ -120,6 +120,14 @@ MongoDB offers the following system variables:
        </reference/atlas-search/facet/#search_meta-aggregation-variable>` 
        and :atlas:`count </reference/atlas-search/counting/#search_meta-aggregation-variable>`.
 
+   * - .. variable:: USER_ROLES
+
+     - Returns the :ref:`roles <roles>` assigned to the current user.
+
+       .. include:: /includes/user-roles-system-variable-examples-list.rst
+
+       .. versionadded:: 7.0
+
 .. seealso::
 
    - :expression:`$let`
diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt
diff --git a/source/reference/operator/aggregation/setIntersection.txt b/source/reference/operator/aggregation/setIntersection.txt
diff --git a/source/release-notes/7.0.txt b/source/release-notes/7.0.txt

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+To use a system variable, add ``$$`` to the start of the variable name.
	`2`	+The ``USER_ROLES`` system variable is specified as ``$$USER_ROLES`` as
	`3`	`+shown in the following example.`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +Run:
++
 +.. code-block:: javascript
++
 +   db.auth( "Jane", "je009" )