Filter operators for collections

Many Data API commands, like Find documents, accept a filter parameter to determine which documents to return or update. The filter parameter uses one or more filter operators.

You must use & to escape any . or & in field names in a filter. Dot notation, which is used to reference nested fields, should not be escaped. For more information, see Work with . and & in field names.

Operators

You can use the following operators in a filter. All operators are case-sensitive.

Equal (default)

The $eq operator matches documents where the specified field is equal to the specified value.

You can’t use this operator on the $lexical field.

This is the default when you don’t specify an operator, except when you filter on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$eq": 714}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $eq: 714 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.eq("number_of_pages", 714);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("number_of_pages", 714);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$eq": 714}}
  }
}'

Not equal

The $ne operator matches documents where the specified field is not equal to the specified value.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$ne": 300}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $ne: 300 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.ne("number_of_pages", 300);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Ne("number_of_pages", 300);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$ne": 300}}
  }
}'

Greater than

The $gt operator matches documents where the specified field is greater than the specified value.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$gt": 300}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $gt: 300 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.gt("number_of_pages", 300);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Gt("number_of_pages", 300);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$gt": 300}}
  }
}'

Greater than or equal

The $gte operator matches documents where the specified field is greater than or equal to the specified value.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$gte": 300}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $gte: 300 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.gte("number_of_pages", 300);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Gte("number_of_pages", 300);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$gte": 300}}
  }
}'

Less than

The $lt operator matches documents where the specified field is less than the specified value.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$lt": 300}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $lt: 300 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.lt("number_of_pages", 300);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Lt("number_of_pages", 300);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$lt": 300}}
  }
}'

Less than or equal

The $lte operator matches documents where the specified field is less than or equal to the specified value.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"number_of_pages": {"$lte": 300}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ number_of_pages: { $lte: 300 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.lte("number_of_pages", 300);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Lte("number_of_pages", 300);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"number_of_pages": {"$lte": 300}}
  }
}'

In

The $in operator matches documents where the field contains any of the specified values. For fields that store an array, the operator matches documents where the array contains any of the specified values.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"genres": {"$in": ["Fantasy", "Romance"]}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    genres: { $in: ["Fantasy", "Romance"] },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.in("genres", "Fantasy", "Romance");

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.In("genres", ["Fantasy", "Romance"]);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"genres": {"$in": ["Fantasy", "Romance"]}}
  }
}'

If you have only one value to match, you can use the single value instead of an array, like { "$in": "VALUE" }.

Not in

The $nin operator matches documents where the field doesn’t contain any of the specified values.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"genres": {"$nin": ["Fantasy", "Romance"]}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    genres: { $nin: ["Fantasy", "Romance"] },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.nin("genres", "Fantasy", "Romance");

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Nin("genres", ["Fantasy", "Romance"]);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"genres": {"$nin": ["Fantasy", "Romance"]}}
  }
}'

Exists

The $exists operator matches documents that have the specified field, even if the field value is null.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"borrower": {"$exists": True}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ borrower: { $exists: true } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.exists("borrower");

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Exists("borrower");

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"borrower": {"$exists": true}}
  }
}'

All

For fields that store an array, the $all operator matches documents where the array contains all of the specified values.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"genres": {"$all": ["Fantasy", "Romance"]}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    genres: { $all: ["Fantasy", "Romance"] },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.all("genres", "Fantasy", "Romance");

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.All("genres", ["Fantasy", "Romance"]);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"genres": {"$all": ["Fantasy", "Romance"]}}
  }
}'

Size

For fields that store an array, the $size operator matches documents where the array has the specified number of elements.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"genres": {"$size": 3}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({ genres: { $size: 3 } });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.hasSize("genres", 3);

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Size("genres", 3);

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"genres": {"$size": 3}}
  }
}'

Not

The $not operator returns documents that don’t match the condition of the clause.

You can’t use this operator on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"$not": {"is_checked_out": False}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    $not: { is_checked_out: false },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.not(Filters.eq("is_checked_out", false));

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Not(
      filterBuilder.Eq("is_checked_out", false)
    );

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"$not": {"is_checked_out": false}}
  }
}'

Match

Lexicographical matching is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

The $match operator finds documents whose $lexical field value is a lexicographical match to the specified string of space-separated keywords or terms.

You can only use the $match operator on the $lexical field. This is the only operator that the $lexical field supports.

This is the default operator when you don’t specify an operator and filter on the $lexical field.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"$lexical": {"$match": "tree hill"}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    $lexical: { $match: "tree hill" },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Optional<Document> result = collection.findOne(Filters.match("tree hill"));

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filter = Builders<Document>.CollectionFilter.LexicalMatch(
      "tree hill"
    );

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"$lexical": {"$match": "tree hill"}}
  }
}'

Combine operators (And, Or)

The $and operator joins clauses with a logical AND. Only documents that match the conditions of all clauses are returned.

The $or operator joins clauses with a logical OR. Documents that match the condition of any of the clauses are returned.

You can use $and and $or separately or together. If you want to match multiple flexible conditions, use $and and $or together in the same filter:

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one(
    {
        "$and": [
            {
                "$or": [
                    {"is_checked_out": False},
                    {"number_of_pages": {"$lt": 300}},
                ]
            },
            {
                "$or": [
                    {"genres": {"$in": ["Fantasy", "Romance"]}},
                    {"publication_year": {"$gte": 2002}},
                ]
            },
        ]
    }
)

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    $and: [
      {
        $or: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
      },
      {
        $or: [
          { genres: { $in: ["Fantasy", "Romance"] } },
          { publication_year: { $gte: 2002 } },
        ],
      },
    ],
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter =
        Filters.and(
            Filters.or(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300)),
            Filters.or(
                Filters.in("genres", "Fantasy", "Romance"), Filters.gte("publication_year", 2002)));

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.And(
      filterBuilder.Or(
        filterBuilder.Eq("is_checked_out", false),
        filterBuilder.Lt("number_of_pages", 300)
      ),
      filterBuilder.Or(
        filterBuilder.In("genres", ["Fantasy", "Romance"]),
        filterBuilder.Gte("publication_year", 2002)
      )
    );

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {
      "$and": [
        {
          "$or": [
            { "is_checked_out": false },
            {"number_of_pages": {"$lt": 300}}
          ]
        },
        {
          "$or": [
            {"genres": {"$in": ["Fantasy", "Romance"]}},
            {"publication_year": {"$gte": 2002}}
          ]
        }
      ]
    }
  }
}'

To filter on a range of values, use $and with $lt/$lte and $gt/$gte:

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one(
    {
        "$and": [
            {"number_of_pages": {"$lt": 300}},
            {"number_of_pages": {"$gte": 200}},
        ]
    }
)

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    $and: [
      { number_of_pages: { $lt: 300 } },
      { number_of_pages: { $gte: 200 } },
    ],
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter =
        Filters.and(Filters.lt("number_of_pages", 300), Filters.gte("number_of_pages", 200));

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.And(
      filterBuilder.Lt("number_of_pages", 300),
      filterBuilder.Gte("number_of_pages", 200)
    );

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"$and": [
      {"number_of_pages": {"$lt": 300}},
      {"number_of_pages": {"$gte": 200}}
    ]}
  }
}'

Filter nested fields

Use dot notation to filter nested fields. For example, field.subfield.subsubfield.

  • Python

  • TypeScript

  • Java

  • C#

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Find a document
result = collection.find_one({"metadata.language": {"$eq": "French"}})

print(result)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Find a document
(async function () {
  const result = await collection.findOne({
    "metadata.language": { $eq: "French" },
  });

  console.log(result);
})();
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Find a document
    Filter filter = Filters.eq("metadata.language", "French");

    Optional<Document> result = collection.findOne(filter);

    System.out.println(result);
  }
}

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing collection
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var collection = database.GetCollection("COLLECTION_NAME");

    // Find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "French");

    var result = await collection.FindOneAsync(filter);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOne": {
    "filter": {"metadata.language": {"$eq": "French"}}
  }
}'

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM