Implementation:Recommenders team Recommenders Cosmos CLI

Knowledge Sources	Recommenders
Domains	Recommender Systems, Data Storage, Azure Integration
Last Updated	2026-02-10 00:00 GMT

Overview

Provides helper functions for interacting with Azure Cosmos DB (DocumentDB API) to find and read databases and collections.

Description

The cosmos_cli module offers four utility functions for working with Azure Cosmos DB via the pydocumentdb client library. find_database and find_collection execute parameterized SQL queries (SELECT * FROM r WHERE r.id=@id) against the Cosmos DB service to check whether a database or collection exists, returning boolean results. read_database and read_collection retrieve actual database or collection objects by constructing resource links (e.g., dbs/{id} and dbs/{dbid}/colls/{id}) and calling the corresponding read methods on the client. Both read functions handle 404 errors gracefully by printing a message rather than raising an exception, while re-raising other HTTP errors.

Usage

Use these functions when recommendation data or experiment results are stored in Azure Cosmos DB. Call find_database or find_collection to verify existence before attempting reads, and use read_database or read_collection to retrieve the actual resource objects for further operations.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/datasets/cosmos_cli.py
• Lines: 1-98

Signature

def find_collection(client, dbid, id) -> bool

def read_collection(client, dbid, id) -> object

def read_database(client, id) -> object

def find_database(client, id) -> bool

Import

from recommenders.datasets.cosmos_cli import (
    find_collection,
    read_collection,
    read_database,
    find_database,
)

I/O Contract

Inputs

Name	Type	Required	Description
client	object	Yes	A pydocumentdb client object connected to a Cosmos DB account.
dbid	str	Yes (for collection functions)	Database ID within the Cosmos DB account.
id	str	Yes	Collection ID (for collection functions) or Database ID (for database functions).

Outputs

Name	Type	Description
return (find_collection)	bool	True if the collection exists, False otherwise.
return (read_collection)	object or None	The collection object if found, None if a 404 error occurs.
return (read_database)	object or None	The database object if found, None if a 404 error occurs.
return (find_database)	bool	True if the database exists, False otherwise.

Usage Examples

Basic Usage

import pydocumentdb.document_client as document_client
from recommenders.datasets.cosmos_cli import (
    find_database,
    find_collection,
    read_database,
    read_collection,
)

# Create a Cosmos DB client
client = document_client.DocumentClient(
    "https://myaccount.documents.azure.com:443/",
    {"masterKey": "my-key"},
)

# Check if a database exists
if find_database(client, "recommendations_db"):
    db = read_database(client, "recommendations_db")

    # Check if a collection exists within the database
    if find_collection(client, "recommendations_db", "user_ratings"):
        collection = read_collection(client, "recommendations_db", "user_ratings")

Dependencies

• pydocumentdb - Azure Cosmos DB (DocumentDB API) client library