Find

OneNode allows you to query and retrieve documents from a collection using the same syntax as MongoDB's find() functionality. Start with simple queries and add complexity as needed.

Basic Find Operations

The simplest way to get started is to find all documents or use basic filters:

# Simple find - get all documents
all_docs = collection.find({})
print(f"Found {len(all_docs)} documents")

# Find with a basic filter
adults = collection.find({"age": {"$gte": 18}})
for doc in adults:
    print(f"Name: {doc['name']}, Age: {doc['age']}")

Basic Response

A successful find operation will return a JSON array containing the matching documents in the collection. Here's an example response:

[
  {
    "_id": ObjectId("64d2f8f01234abcd5678ef90"),
    "name": "Alice Smith",
    "age": 29,
    "city": "New York"
  },
  {
    "_id": ObjectId("64d2f8f01234abcd5678ef91"),
    "name": "Bob Johnson",
    "age": 40,
    "city": "New York"
  }
]

Advanced Find Operations

For more control over your queries, you can customize the find operation with additional parameters. These parameters allow you to control which fields are returned, sort results, and implement pagination.

Using Projection

The projection parameter controls which fields are included or excluded in the returned documents.

# Find with projection to include only specific fields
filter_criteria = {"age": {"$gt": 25}}

projection = {
    "mode": "include",
    "fields": ["name", "age"]
}

response = collection.find(filter_criteria, projection)

for doc in response:
    print(f"Name: {doc['name']}, Age: {doc['age']}")
    # Note: Other fields like 'city' will not be included

📖 Learn More

For comprehensive projection syntax and advanced examples, see our Projection Syntax Guide.

Using Sort

The sort parameter allows you to specify the sort order for the result set.

# Find with sort - ascending and descending order
filter_criteria = {"city": "New York"}

# Sort by age in descending order
sort = {"age": -1}

response = collection.find(filter_criteria, sort=sort)

for doc in response:
    print(f"Name: {doc['name']}, Age: {doc['age']}")
    
# Multiple field sorting
sort_multiple = {"age": -1, "name": 1}  # Age desc, then name asc
response = collection.find(filter_criteria, sort=sort_multiple)

Using Limit

The limit parameter controls the maximum number of documents returned.

# Find with limit to get only top results
filter_criteria = {"status": "active"}
limit = 5

response = collection.find(filter_criteria, limit=limit)

print(f"Found {len(response)} documents (limited to {limit})")
for doc in response:
    print(f"Name: {doc['name']}, Status: {doc['status']}")

Using Skip for Pagination

The skip parameter allows you to skip a specified number of documents, which is useful for implementing pagination.

# Find with skip for pagination
filter_criteria = {"department": "Engineering"}
limit = 10
skip = 20  # Skip first 20 documents (page 3 if 10 per page)

response = collection.find(filter_criteria, limit=limit, skip=skip)

print(f"Page 3 results (skipped {skip}, showing up to {limit}):")
for i, doc in enumerate(response, 1):
    print(f"{skip + i}. {doc['name']} - {doc['department']}")
    
# Helper function for pagination
def get_page(page_num, page_size=10):
    skip_count = (page_num - 1) * page_size
    return collection.find({}, limit=page_size, skip=skip_count)

Parameters for Find Operations

Parameter	Description
filter	A query object to match the documents to retrieve. This works the same way as MongoDB filters, allowing you to specify conditions to find the documents. For more details, refer to the filter operator syntax.
projection (optional)	A field specification object to control which fields are returned in the result set. Uses OneNode's simplified projection syntax with `mode` and `fields`. For more details, refer to the projection operator syntax.
sort (optional)	An object specifying the sort order for the result set (e.g., `{ "age": 1 }` to sort by `age` in ascending order, or `{ "age": -1 }` for descending).
limit (optional)	A number to limit the number of documents returned.
skip (optional)	A number to skip the first `n` documents in the result set, useful for pagination.

How can we improve this documentation?

Share Your Thoughts

Your feedback helps us improve our documentation. Let us know what you think!