Search API

class Search:
    """Search for resources using various criteria and expressions.
    
    Provides a fluent interface for building complex search queries with filtering,
    sorting, aggregation, and pagination capabilities.
    """
    
    def __init__(self):
        """Initialize a new search query."""
    
    def expression(self, value):
        """Set the search expression to filter resources.
        
        Args:
            value (str): Search expression using Cloudinary search syntax.
                        Examples:
                        - "cat AND tags:kitten"
                        - "resource_type:image AND format:jpg"
                        - "created_at>1d AND bytes>1mb"
                        - "folder:products/* AND width>500"
        
        Returns:
            Search: Self for method chaining
        """
    
    def max_results(self, value):
        """Set maximum number of results to return.
        
        Args:
            value (int): Maximum results (1-500, default: 50)
        
        Returns:
            Search: Self for method chaining
        """
    
    def next_cursor(self, value):
        """Set cursor for pagination.
        
        Args:
            value (str): Cursor token from previous search result
        
        Returns:
            Search: Self for method chaining
        """
    
    def sort_by(self, field, direction="desc"):
        """Add sort criteria to the search.
        
        Args:
            field (str): Field to sort by ('created_at', 'uploaded_at', 'public_id', 'filename', 'format', 'resource_type', 'type', 'bytes', 'width', 'height', 'aspect_ratio', 'pixels', 'duration', 'bit_rate', 'frame_rate')
            direction (str, optional): Sort direction ('asc', 'desc', default: 'desc')
        
        Returns:
            Search: Self for method chaining
        """
    
    def aggregate(self, value):
        """Add aggregation to the search results.
        
        Args:
            value (str): Aggregation field ('resource_type', 'type', 'format', 'bytes', 'width', 'height', 'aspect_ratio', 'pixels', 'created_at', 'uploaded_at', 'tags', 'context', 'metadata')
        
        Returns:
            Search: Self for method chaining
        """
    
    def with_field(self, value):
        """Include additional fields in search results.
        
        Args:
            value (str): Field to include ('context', 'metadata', 'tags', 'image_analysis', 'asset_folder', 'display_name')
        
        Returns:
            Search: Self for method chaining
        """
    
    def execute(self, **options):
        """Execute the search query.
        
        Args:
            **options: Additional search options
        
        Returns:
            dict: Search results containing:
                - total_count (int): Total number of matching resources
                - time (int): Search execution time in milliseconds
                - aggregations (dict): Aggregation results (if requested)
                - resources (list): List of matching resources
                - next_cursor (str): Cursor for next page (if more results exist)
                - rate_limit_allowed (int): Rate limit quota
                - rate_limit_reset_at (str): Rate limit reset time
                - rate_limit_remaining (int): Remaining rate limit quota
        """

class SearchFolders(Search):
    """Search for folders in your Cloudinary account.
    
    Provides folder-specific search capabilities with hierarchical filtering.
    Inherits all methods from the Search class but targets the folders endpoint.
    """
    
    def __init__(self):
        """Initialize a new folder search query.
        
        Automatically sets the search endpoint to 'folders' instead of 'resources'.
        """
    
    def expression(self, value):
        """Set the folder search expression.
        
        Args:
            value (str): Search expression for folders using folder-specific criteria.
                        Examples:
                        - "name:product*" (folders starting with 'product')
                        - "path:images/products/*" (folders in specific path)
                        - "created_at:>30d" (folders created in last 30 days)
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def max_results(self, value):
        """Set maximum number of folder results to return.
        
        Args:
            value (int): Maximum results (1-500, default: 50)
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def next_cursor(self, value):
        """Set cursor for folder pagination.
        
        Args:
            value (str): Cursor token from previous search result
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def sort_by(self, field, direction="desc"):
        """Add sort criteria for folders.
        
        Args:
            field (str): Field to sort by ('name', 'created_at', 'path', 'external_id')
            direction (str, optional): Sort direction ('asc', 'desc', default: 'desc')
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def aggregate(self, value):
        """Add aggregation to folder search results.
        
        Args:
            value (str): Aggregation field for folders ('name', 'path', 'created_at')
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def with_field(self, value):
        """Include additional fields in folder search results.
        
        Args:
            value (str): Field to include ('external_id', 'metadata')
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def fields(self, value):
        """Request specific fields to return in the folder result set.
        
        Args:
            value (str): Comma-separated list of fields to include in results
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def ttl(self, ttl):
        """Set the time to live of the search URL.
        
        Args:
            ttl (int): The time to live in seconds
        
        Returns:
            SearchFolders: Self for method chaining
        """
    
    def to_url(self, ttl=None, next_cursor=None, **options):
        """Create a signed Search URL for folders that can be used on the client side.
        
        Args:
            ttl (int, optional): The time to live in seconds
            next_cursor (str, optional): Starting position
            **options: Additional url delivery options including api_secret
        
        Returns:
            str: The resulting folder search URL
        """
    
    def to_json(self):
        """Convert the folder search query to JSON string.
        
        Returns:
            str: JSON representation of the search query
        """
    
    def as_dict(self):
        """Convert the folder search query to dictionary format.
        
        Returns:
            dict: Dictionary representation of the search query
        """
    
    def execute(self, **options):
        """Execute the folder search query.
        
        Args:
            **options: Additional search options
        
        Returns:
            dict: Folder search results containing:
                - total_count (int): Total number of matching folders
                - time (int): Search execution time in milliseconds
                - aggregations (dict): Aggregation results (if requested)
                - folders (list): List of matching folders with properties:
                    - name (str): Folder name
                    - path (str): Full folder path
                    - external_id (str): External identifier (if set)
                    - created_at (str): Creation timestamp
                - next_cursor (str): Cursor for next page (if more results exist)
                - rate_limit_allowed (int): Rate limit quota
                - rate_limit_reset_at (str): Rate limit reset time
                - rate_limit_remaining (int): Remaining rate limit quota
        """

def Search():
    """Create a new Search instance.
    
    Returns:
        Search: New search query builder
    """

def SearchFolders():
    """Create a new SearchFolders instance.
    
    The SearchFolders class inherits from Search but automatically targets
    the folders endpoint for searching folder structures instead of assets.
    
    Returns:
        SearchFolders: New folder search query builder
    """

from cloudinary.search import Search

# Create and execute a simple search
search = Search()
result = search.expression("cat").execute()
print(f"Found {result['total_count']} resources with 'cat'")

# Method chaining
result = Search() \
    .expression("resource_type:image AND format:jpg") \
    .max_results(100) \
    .sort_by("created_at", "asc") \
    .execute()

# Search with multiple criteria
result = Search() \
    .expression("tags:product AND bytes:>1mb AND width:>800") \
    .max_results(50) \
    .execute()

# Search by date range
result = Search() \
    .expression("created_at:[2023-01-01 TO 2023-12-31]") \
    .sort_by("created_at", "desc") \
    .execute()

# Search with complex boolean logic
result = Search() \
    .expression("(tags:summer OR tags:beach) AND format:jpg AND bytes:<5mb") \
    .execute()

# Search by folder and metadata
result = Search() \
    .expression("folder:products/* AND metadata.category:electronics") \
    .with_field("metadata") \
    .execute()

# Search recent large images
result = Search() \
    .expression("resource_type:image AND created_at:>7d AND bytes:>2mb") \
    .sort_by("bytes", "desc") \
    .execute()

# Get format distribution
result = Search() \
    .expression("resource_type:image") \
    .aggregate("format") \
    .max_results(0) \
    .execute()

format_counts = result['aggregations']['format']
for format_info in format_counts:
    print(f"{format_info['value']}: {format_info['count']} images")

# Multiple aggregations
result = Search() \
    .expression("tags:product") \
    .aggregate("format") \
    .aggregate("resource_type") \
    .aggregate("bytes") \
    .max_results(0) \
    .execute()

# Tag analysis
result = Search() \
    .expression("created_at:>30d") \
    .aggregate("tags") \
    .max_results(0) \
    .execute()

# Paginate through search results
all_resources = []
next_cursor = None

while True:
    search = Search() \
        .expression("resource_type:image AND tags:product") \
        .max_results(500) \
        .sort_by("created_at", "desc")
    
    if next_cursor:
        search.next_cursor(next_cursor)
    
    result = search.execute()
    all_resources.extend(result['resources'])
    
    next_cursor = result.get('next_cursor')
    if not next_cursor:
        break

print(f"Total resources found: {len(all_resources)}")

from cloudinary.search_folders import SearchFolders

# Basic folder search by name pattern
result = SearchFolders() \
    .expression("name:product*") \
    .max_results(100) \
    .sort_by("name", "asc") \
    .execute()

print(f"Found {result['total_count']} folders")
for folder in result['folders']:
    print(f"Folder: {folder['name']} (path: {folder['path']})")

# Search folders by creation date
result = SearchFolders() \
    .expression("created_at:>30d") \
    .sort_by("created_at", "desc") \
    .execute()

# Search folders by path prefix
result = SearchFolders() \
    .expression("path:images/products/*") \
    .with_field("external_id") \
    .execute()

# Search with aggregation to analyze folder structure
result = SearchFolders() \
    .expression("created_at:>90d") \
    .aggregate("path") \
    .max_results(0) \
    .execute()

# Get folder distribution by creation date
for agg_item in result['aggregations']['path']:
    print(f"Path: {agg_item['value']}, Count: {agg_item['count']}")

# Complex folder search with multiple criteria
result = SearchFolders() \
    .expression("name:temp* OR path:*/temp/* AND created_at:<7d") \
    .sort_by("path", "asc") \
    .max_results(50) \
    .execute()

# Paginate through all folders
all_folders = []
next_cursor = None

while True:
    search = SearchFolders() \
        .expression("*") \
        .max_results(500) \
        .sort_by("name", "asc")
    
    if next_cursor:
        search.next_cursor(next_cursor)
    
    result = search.execute()
    all_folders.extend(result['folders'])
    
    next_cursor = result.get('next_cursor')
    if not next_cursor:
        break

print(f"Total folders: {len(all_folders)}")

# Generate a signed URL for folder search (client-side usage)
search_url = SearchFolders() \
    .expression("name:upload*") \
    .max_results(100) \
    .to_url(ttl=3600, api_secret="your_api_secret")

print(f"Folder search URL: {search_url}")

# Include all available metadata in results
result = Search() \
    .expression("tags:featured") \
    .with_field("context") \
    .with_field("metadata") \
    .with_field("tags") \
    .with_field("image_analysis") \
    .max_results(10) \
    .execute()

for resource in result['resources']:
    print(f"Public ID: {resource['public_id']}")
    print(f"  Tags: {resource.get('tags', [])}")
    print(f"  Context: {resource.get('context', {})}")
    print(f"  Metadata: {resource.get('metadata', {})}")
    if 'image_analysis' in resource:
        print(f"  Colors: {resource['image_analysis'].get('colors', [])}")

# Search without fetching resources (aggregation only)
result = Search() \
    .expression("resource_type:image") \
    .aggregate("format") \
    .aggregate("bytes") \
    .max_results(0) \
    .execute()

# Efficient search with minimal fields
result = Search() \
    .expression("tags:thumbnail") \
    .sort_by("created_at", "desc") \
    .max_results(100) \
    .execute()

# Only get public_id and basic info
for resource in result['resources']:
    public_id = resource['public_id']
    format = resource['format']
    bytes_size = resource['bytes']
    print(f"{public_id}.{format} ({bytes_size} bytes)")