Skip to main content

Query Guide

KeraDB supports MongoDB-compatible query operators for powerful data retrieval and manipulation.

Basic Queries​

Exact Match​

// Find by single field
const user = await users.findOne({ name: 'Alice' });

// Find by multiple fields
const user = await users.findOne({ 
  name: 'Alice', 
  age: 28 
});

// Find all matching documents
const developers = await users.find({ role: 'developer' }).toArray();

Comparison Operators​

$eq (Equal)​

Matches values that are equal to a specified value.

const users = await users.find({ age: { $eq: 25 } }).toArray();
// Same as: { age: 25 }

$ne (Not Equal)​

Matches values that are not equal to a specified value.

const users = await users.find({ role: { $ne: 'admin' } }).toArray();

$gt, $gte (Greater Than, Greater Than or Equal)​

// Greater than
const adults = await users.find({ age: { $gt: 18 } }).toArray();

// Greater than or equal
const voters = await users.find({ age: { $gte: 18 } }).toArray();

$lt, $lte (Less Than, Less Than or Equal)​

// Less than
const minors = await users.find({ age: { $lt: 18 } }).toArray();

// Less than or equal
const eligible = await users.find({ age: { $lte: 65 } }).toArray();

$in (In Array)​

Matches any of the values specified in an array.

const staff = await users.find({ 
  role: { $in: ['admin', 'moderator', 'editor'] } 
}).toArray();

$nin (Not In Array)​

Matches none of the values specified in an array.

const regularUsers = await users.find({ 
  role: { $nin: ['admin', 'moderator'] } 
}).toArray();

Logical Operators​

$and​

Joins query clauses with a logical AND.

const result = await users.find({
  $and: [
    { age: { $gte: 18 } },
    { role: 'developer' },
    { active: true }
  ]
}).toArray();

$or​

Joins query clauses with a logical OR.

const result = await users.find({
  $or: [
    { role: 'admin' },
    { role: 'moderator' },
    { permissions: 'superuser' }
  ]
}).toArray();

$not​

Inverts the effect of a query expression.

const result = await users.find({
  age: { $not: { $lt: 18 } }
}).toArray();

$nor​

Joins query clauses with a logical NOR.

const result = await users.find({
  $nor: [
    { role: 'admin' },
    { banned: true }
  ]
}).toArray();

Element Operators​

$exists​

Matches documents that have the specified field.

// Find users with email field
const withEmail = await users.find({ 
  email: { $exists: true } 
}).toArray();

// Find users without phone field
const withoutPhone = await users.find({ 
  phone: { $exists: false } 
}).toArray();

$type​

Selects documents if a field is of the specified type.

const stringIds = await users.find({ 
  _id: { $type: 'string' } 
}).toArray();

const numericAges = await users.find({ 
  age: { $type: 'number' } 
}).toArray();

Array Operators​

$all​

Matches arrays that contain all elements specified in the query.

const experts = await users.find({
  skills: { $all: ['JavaScript', 'Python', 'Docker'] }
}).toArray();

$elemMatch​

Matches documents that contain an array field with at least one element matching all criteria.

const results = await orders.find({
  items: {
    $elemMatch: {
      price: { $gte: 100 },
      quantity: { $gt: 1 }
    }
  }
}).toArray();

$size​

Matches arrays with a specified number of elements.

const threeSkills = await users.find({
  skills: { $size: 3 }
}).toArray();

String Operators​

$regex​

Provides regular expression pattern matching.

// Case-insensitive search
const gmailUsers = await users.find({
  email: { $regex: /gmail\.com$/i }
}).toArray();

// Find names starting with 'A'
const aNames = await users.find({
  name: { $regex: /^A/ }
}).toArray();

Update Operators​

$set​

Sets the value of a field.

await users.updateOne(
  { email: 'alice@example.com' },
  { $set: { age: 29, role: 'senior developer' } }
);

$unset​

Removes a field from a document.

await users.updateOne(
  { email: 'bob@example.com' },
  { $unset: { tempField: '' } }
);

$inc​

Increments the value of a field by a specified amount.

await users.updateOne(
  { email: 'alice@example.com' },
  { $inc: { loginCount: 1, points: 10 } }
);

$push​

Adds an element to an array.

await users.updateOne(
  { email: 'alice@example.com' },
  { $push: { skills: 'TypeScript' } }
);

$pull​

Removes all array elements that match a specified query.

await users.updateOne(
  { email: 'alice@example.com' },
  { $pull: { skills: 'jQuery' } }
);

$addToSet​

Adds elements to an array only if they do not already exist.

await users.updateOne(
  { email: 'alice@example.com' },
  { $addToSet: { skills: 'React' } }
);

Query Modifiers​

Sorting​

// Sort ascending
const users = await users.find().sort({ age: 1 }).toArray();

// Sort descending
const users = await users.find().sort({ age: -1 }).toArray();

// Multiple sort fields
const users = await users.find()
  .sort({ role: 1, age: -1 })
  .toArray();

Limiting Results​

// Get first 10 results
const users = await users.find().limit(10).toArray();

// Skip and limit (pagination)
const page2 = await users.find()
  .skip(10)
  .limit(10)
  .toArray();

Field Projection​

Select which fields to return.

// Include only specific fields
const users = await users.find({}, { 
  name: 1, 
  email: 1 
}).toArray();

// Exclude specific fields
const users = await users.find({}, { 
  password: 0, 
  internalId: 0 
}).toArray();

Complex Query Examples​

Combining Multiple Operators​

const result = await users.find({
  $and: [
    { age: { $gte: 18, $lte: 65 } },
    { 
      $or: [
        { role: 'developer' },
        { role: 'designer' }
      ]
    },
    { skills: { $all: ['JavaScript', 'React'] } },
    { email: { $exists: true } }
  ]
}).sort({ createdAt: -1 }).limit(20).toArray();

Next Steps​