Adds how to query for Null or Missing Fields information. (#5821) (#5858)

MongoCaleb · jeff-allen-mongo · web-flow · commit 7d7f536c1fa0 · 2024-01-18T10:56:21.000-05:00
* new $ne examples; remove perl tabs

* another attempt to remove perl

* simplify ruby example

* review changes

* Update source/tutorial/query-for-null-fields.txt



---------

Co-authored-by: Jeff Allen &lt;jeffrey.allen@10gen.com&gt;
diff --git a/source/includes/driver-examples/driver-example-query-38.rst b/source/includes/driver-examples/driver-example-query-38.rst
@@ -76,15 +76,6 @@
             :start-after: Start Example 38
             :end-before: End Example 38
 
-     - id: perl
-       content: |
-
-         .. literalinclude:: /driver-examples/driver-examples.t
-            :language: perl
-            :dedent: 4
-            :start-after: Start Example 38
-            :end-before: End Example 38
-
      - id: ruby
        content: |
 
diff --git a/source/includes/driver-examples/driver-example-query-39.rst b/source/includes/driver-examples/driver-example-query-39.rst
@@ -75,15 +75,6 @@
             :start-after: Start Example 39
             :end-before: End Example 39
 
-     - id: perl
-       content: |
-
-         .. literalinclude:: /driver-examples/driver-examples.t
-            :language: perl
-            :dedent: 4
-            :start-after: Start Example 39
-            :end-before: End Example 39
-
      - id: ruby
        content: |
 
diff --git a/source/includes/driver-examples/driver-example-query-40.rst b/source/includes/driver-examples/driver-example-query-40.rst
@@ -75,15 +75,6 @@
             :start-after: Start Example 40
             :end-before: End Example 40
 
-     - id: perl
-       content: |
-
-         .. literalinclude:: /driver-examples/driver-examples.t
-            :language: perl
-            :dedent: 4
-            :start-after: Start Example 40
-            :end-before: End Example 40
-
      - id: ruby
        content: |
 
diff --git a/source/includes/driver-examples/driver-example-query-41.rst b/source/includes/driver-examples/driver-example-query-41.rst
@@ -75,15 +75,6 @@
             :start-after: Start Example 41
             :end-before: End Example 41
 
-     - id: perl
-       content: |
-
-         .. literalinclude:: /driver-examples/driver-examples.t
-            :language: perl
-            :dedent: 4
-            :start-after: Start Example 41
-            :end-before: End Example 41
-
      - id: ruby
        content: |
 
diff --git a/source/includes/driver-examples/driver-example-query-intro-no-perl.rst b/source/includes/driver-examples/driver-example-query-intro-no-perl.rst
@@ -0,0 +1,123 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: shell
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :method:`db.collection.find()` method in :binary:`mongosh`.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: compass
+       content: |
+        
+         This page provides examples of |query_operations| using
+         :ref:`MongoDB Compass <compass-index>`. 
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: python
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :py:meth:`pymongo.collection.Collection.find` method in the
+         :api:`PyMongo <pymongo>`
+         Python driver.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: motor
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.find`
+         method in the `Motor <https://motor.readthedocs.io/en/stable/>`_
+         driver.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: java-sync
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         com.mongodb.client.MongoCollection.find_ method in the MongoDB
+         `Java Synchronous Driver`_.
+
+         .. tip::
+
+            The driver provides com.mongodb.client.model.Filters_
+            helper methods to facilitate the creation of filter
+            documents. The examples on this page use these methods to
+            create the filter documents.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: java-async
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         `com.mongodb.reactivestreams.client.MongoCollection.find <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#find()>`_
+         method in the MongoDB `Java Reactive Streams Driver <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/>`_.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: nodejs
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :node-api:`Collection.find() <Collection.html#find>` method in
+         the :node-docs:`MongoDB Node.js Driver <>`.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: php
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :phpmethod:`MongoDB\\Collection::find() <phpmethod.MongoDB\\Collection::find>`
+         method in the
+         `MongoDB PHP Library <https://www.mongodb.com/docs/drivers/php-libraries/>`_.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: ruby
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :ruby-api:`Mongo::Collection#find()<Collection.html#find-instance_method>`
+         method in the
+         :ruby:`MongoDB Ruby Driver </>`.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: scala
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :scala-api:`collection.find()<find[C](filter:org.mongodb.scala.bson.conversions.Bson)(implicite:org.mongodb.scala.bson.DefaultHelper.DefaultsTo[C,TResult],implicitct:scala.reflect.ClassTag[C]):org.mongodb.scala.FindObservable[C]>` method
+         in the
+         `MongoDB Scala Driver <http://mongodb.github.io/mongo-scala-driver/>`_.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: csharp
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :csharp-api:`MongoCollection.Find() <M_MongoDB_Driver_MongoCollection_1_Find>`
+         method in the
+         `MongoDB C# Driver <https://mongodb.github.io/mongo-csharp-driver/>`_.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
+     - id: go
+       content: |
+        
+         This page provides examples of |query_operations| using the
+         :go-api:`Collection.Find <mongo#Collection.Find>`
+         function in the
+         `MongoDB Go Driver <https://github.com/mongodb/mongo-go-driver/>`_.
+
+         .. include:: /includes/driver-examples/examples-intro.rst
+
diff --git a/source/tutorial/query-for-null-fields.txt b/source/tutorial/query-for-null-fields.txt
@@ -6,12 +6,12 @@
 ================================
 Query for Null or Missing Fields
 ================================
-
+  
 .. default-domain:: mongodb
 
 .. facet::
    :name: programming_language
-   :values: shell, csharp, go, java, javascript/typescript, perl, php, python, ruby, scala
+   :values: shell, csharp, go, java, javascript/typescript, php, python, ruby, scala
 
 .. meta:: 
    :keywords: java sync, java async, reactive streams, motor, code example, node.js, compass
@@ -36,7 +36,7 @@ Different query operators in MongoDB treat ``null`` values differently.
 
 .. |query_operations| replace:: operations that query for ``null`` values
 
-.. include:: /includes/driver-examples/driver-example-query-intro.rst
+.. include:: /includes/driver-examples/driver-example-query-intro-no-perl.rst
 
 .. tabs-drivers::
 
@@ -53,12 +53,6 @@ Different query operators in MongoDB treat ``null`` values differently.
             Use ``None`` with the Motor driver to
             query for ``null`` or missing fields in MongoDB.
 
-     - id: perl
-       content: |
-         .. important::
-            Use ``undef`` with the MongoDB Perl driver to
-            query for ``null`` or missing fields in MongoDB.
-
      - id: ruby
        content: |
          .. important::
@@ -143,12 +137,6 @@ Equality Filter
          contain the ``item`` field whose value is ``null`` *or* that
          do not contain the ``item`` field.
 
-     - id: perl
-       content: |
-         The ``{ item => undef }`` query matches documents that either
-         contain the ``item`` field whose value is ``null`` *or* that
-         do not contain the ``item`` field.
-
      - id: ruby
        content: |
          The ``{ item => nil }`` query matches documents that either
@@ -178,6 +166,95 @@ Equality Filter
 
 The query returns both documents in the collection.
 
+Non-Equality Filter
+-------------------
+
+To query for fields that **exist** and are **not null**, use the :query:`$ne` 
+operator. The ``{ item : { $ne : null } }`` query matches documents where the
+``item`` field exists *and* has a non-null value.
+
+.. tabs-drivers::
+
+   tabs:
+     - id: shell
+       content: |
+         .. code-block:: sh
+
+            db.inventory.find( { item: { $ne : null } } )
+
+     - id: compass
+       content: |
+         .. code-block:: javascript
+
+            { item: { $ne : null } }
+
+     - id: python
+       content: |
+         .. code-block:: python
+
+            cursor = db.inventory.find( { "item": { "$ne": None } } )
+
+     - id: motor
+       content: |
+         .. code-block:: python
+
+            cursor = db.inventory.find( { "item": { "$ne": None } } )
+
+     - id: java-sync
+       content: |
+         .. code-block:: java
+
+            collection.find($ne("item", null));
+
+     - id: java-async
+       content: |
+         .. code-block:: java
+
+            db.inventory.find( { item: { $ne : nul l} } )
+
+     - id: nodejs
+       content: |
+         .. code-block:: javascript
+
+            const cursor = db.collection('inventory')
+              .find({ item: { $ne : null }
+            });
+
+     - id: php
+       content: |
+         .. code-block:: php
+
+            $cursor = $db->inventory->find(['item' => ['$ne' => null ]]);
+
+     - id: ruby
+       content: |
+         .. code-block:: ruby
+
+            client[:inventory].find(item: { '$ne' => nil })
+            
+     - id: scala
+       content: |
+         .. code-block:: scala
+
+            collection.find($ne("item", null));
+
+     - id: csharp
+       content: |
+         .. code-block:: csharp
+
+            var filter = Builders<BsonDocument>.Filter.Ne("item", BsonNull.Value);
+            var result = collection.Find(filter).ToList();
+
+     - id: go
+       content: |
+         .. code-block:: go
+
+            cursor, err := coll.Find(
+              context.TODO(),
+              bson.D{
+                {"item", bson.D{"$ne": nil}},
+              })
+
 Type Check
 ----------
 
@@ -240,13 +317,6 @@ Type Check
          ``null``; i.e. the value of the ``item`` field is of
          :ref:`BSON Type <bson-types>` ``Null`` (BSON Type 10):
 
-     - id: perl
-       content: |
-         The ``{ item => { $type => 10 } }`` query matches *only*
-         documents that contain the ``item`` field whose value is
-         ``null``; i.e. the value of the ``item`` field is of
-         :ref:`BSON Type <bson-types>` ``Null`` (BSON Type 10):
-
      - id: ruby
        content: |
          The ``{ item => { $type => 10 } }`` query matches *only*
@@ -330,11 +400,6 @@ field. [#type0]_
          The ``[ item => [ $exists => false ] ]`` query matches documents
          that do not contain the ``item`` field:
 
-     - id: perl
-       content: |
-         The ``{ item => { $exists => false } }`` query matches documents
-         that do not contain the ``item`` field:
-
      - id: ruby
        content: |
          The ``{ item => { $exists => false } }`` query matches documents
