Scope

class couchbase.scope.Scope(bucket: Bucket, scope_name: str)

A scope in a bucket: its collections, and the queries and searches run against it.

Warning

couchbase.collection.Scope is deprecated, and will be removed in a future release. Import Scope from couchbase.scope.

Get one from scope().

Parameters:
  • bucket (Bucket) – The bucket the scope belongs to.

  • scope_name (str) – The name of the scope.

analytics_query(statement: str, *options: AnalyticsOptions | str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], **kwargs: Any) → AnalyticsResult

Executes an analaytics query against the scope.

Note

The analytics query is executed lazily in that it is executed once iteration over the AnalyticsResult begins.

See also

Parameters:
  • statement (str) – The analytics SQL++ statement to execute.

  • options (AnalyticsOptions) – Optional parameters for the analytics query operation.

  • **kwargs – keyword arguments that can be used in place or to override provided AnalyticsOptions. A keyword that is not one of its options is sent as a named parameter; prefer AnalyticsOptions(named_parameters=...), which cannot collide with an option name.

Returns:

An instance of a AnalyticsResult which provides access to iterate over the analytics query results and access metadata and metrics about the analytics query.

Return type:

AnalyticsResult

Examples

Note

Be sure to setup the necessary dataverse(s), dataset(s) for your analytics queries. See Analytics Introduction in Couchbase Server docs.

Simple analytics query:

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $1 LIMIT $2;'
q_res = scope.analytics_query(q_str)
for row in q_res.rows():
    print(f'Found row: {row}')

Simple analytics query with positional parameters:

from couchbase.options import AnalyticsOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $1 LIMIT $2;'
q_res = scope.analytics_query(q_str, AnalyticsOptions(positional_parameters=['United%', 5]))
for row in q_res.rows():
    print(f'Found row: {row}')

Simple analytics query with named parameters:

from couchbase.options import AnalyticsOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = scope.analytics_query(q_str,
                                AnalyticsOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from analytics query:

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = scope.analytics_query(q_str)
for row in q_res.rows():
    print(f'Found row: {row}')

print(f'Analytics query metadata: {q_res.metadata()}')
print(f'Analytics query metrics: {q_res.metadata().metrics()}')
property bucket_name: str

The name of the bucket this scope belongs to.

collection(name: str) → Collection

Creates a Collection instance of the specified collection.

Parameters:

name (str) – Name of the collection to reference.

Returns:

A Collection instance of the specified collection.

Return type:

Collection

static default_name() → str

The name of a bucket’s default scope.

eventing_functions() → ScopeEventingFunctionManager

Get a manager for the eventing functions of this scope.

Returns:

A ScopeEventingFunctionManager instance.

Return type:

ScopeEventingFunctionManager

property name: str

The name of this scope.

query(statement: str, *options: QueryOptions | str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], **kwargs: Any) → QueryResult

Executes a N1QL query against the scope.

Note

The query is executed lazily in that it is executed once iteration over the QueryResult begins.

Note

Scope-level queries are only supported on Couchbase Server versions that support scopes and collections.

See also

Parameters:
  • statement (str) – The N1QL statement to execute.

  • options (QueryOptions) – Optional parameters for the query operation.

  • **kwargs – keyword arguments that can be used in place or to override provided QueryOptions. A keyword that is not one of its options is sent as a named parameter; prefer QueryOptions(named_parameters=...), which cannot collide with an option name.

Returns:

An instance of a QueryResult which provides access to iterate over the query results and access metadata and metrics about the query.

Return type:

QueryResult

Examples

Simple query:

q_res = scope.query('SELECT * FROM `inventory` WHERE country LIKE 'United%' LIMIT 2;')
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with positional parameters:

from couchbase.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `inventory` WHERE country LIKE $1 LIMIT $2;'
q_res = scope.query(q_str, QueryOptions(positional_parameters=['United%', 5]))
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from couchbase.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = scope.query(q_str, QueryOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from couchbase.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = scope.query(q_str, QueryOptions(metrics=True))
for row in q_res.rows():
    print(f'Found row: {row}')

print(f'Query metadata: {q_res.metadata()}')
print(f'Query metrics: {q_res.metadata().metrics()}')
search(index: str, request: SearchRequest | SearchQuery, options: SearchOptions | None = None, **kwargs: Unpack[SearchOptionsKwargs]) → SearchResult

Executes an search against the scope.

Note

The search is executed lazily in that it is executed once iteration over the SearchResult begins.

See also

Parameters:
  • index (str) – Name of the search index to use.

  • request (SearchRequest | SearchQuery) –

    Type of search request to perform.

    Deprecated since version 4.7.0: Passing a SearchQuery is deprecated; wrap it with create() instead.

  • options (SearchOptions) – Optional parameters for the search query operation.

  • **kwargs – keyword arguments that can be used in place or to override provided SearchOptions

Returns:

An instance of a SearchResult which provides access to iterate over the search query results and access metadata and metrics about the search query.

Return type:

SearchResult

Examples

Note

Be sure to create a search index prior to executing a search. Also, if an application desires to utilize search row locations, highlighting, etc. make sure the search index is setup appropriately. See Creating Indexes in Couchbase Server docs.

Simple search:

import couchbase.search as search
from couchbase.options import SearchOptions

# ... other code ...

request = search.SearchRequest.create(search.TermQuery('home'))
q_res = scope.search('travel-sample-index', request, SearchOptions(limit=10))

for row in q_res.rows():
    print(f'Found row: {row}')

Simple vector search:

import couchbase.search as search
from couchbase.options import SearchOptions
from couchbase.vector_search import VectorQuery, VectorSearch

# ... other code ...

# NOTE:  the vector is expected to be type list[float], set the vector to the appropriate value,
# this is an example.
vector = [-0.014653487130999565, -0.008658270351588726, 0.017129190266132355, -0.015563474968075752]
vector_search = VectorSearch.from_vector_query(VectorQuery('vector_field', vector))
request = search.SearchRequest.create(vector_search)
q_res = scope.search('travel-sample-vector-index', request, SearchOptions(limit=10))

for row in q_res.rows():
    print(f'Found row: {row}')

Combine search and vector search:

import couchbase.search as search
from couchbase.options import SearchOptions
from couchbase.vector_search import VectorQuery, VectorSearch

# ... other code ...

# NOTE:  the vector is expected to be type list[float], set the vector to the appropriate value,
# this is an example.
vector_search = VectorSearch.from_vector_query(VectorQuery('vector_field', [-0.014653487130999565,
                                                                            -0.008658270351588726,
                                                                            0.017129190266132355,
                                                                            -0.015563474968075752]))
request = search.SearchRequest.create(search.MatchAllQuery()).with_vector_search(vector_search)
q_res = scope.search('travel-sample-vector-index', request, SearchOptions(limit=10))

for row in q_res.rows():
    print(f'Found row: {row}')
search_indexes() → ScopeSearchIndexManager

Get a manager for the search indexes of this scope.

Returns:

A ScopeSearchIndexManager instance.

Return type:

ScopeSearchIndexManager

search_query(index: str, query: SearchQuery, options: SearchOptions | None = None, **kwargs: Unpack[SearchOptionsKwargs]) → SearchResult

Executes an search query against the scope.

Deprecated since version 4.1.11: Use search() instead.

Note

The search query is executed lazily in that it is executed once iteration over the SearchResult begins.

Parameters:
  • index (str) – Name of the search query to use.

  • query (SearchQuery) – Type of search query to perform.

  • options (SearchOptions) – Optional parameters for the search query operation.

  • **kwargs – keyword arguments that can be used in place or to override provided SearchOptions

Returns:

An instance of a SearchResult which provides access to iterate over the search query results and access metadata and metrics about the search query.

Return type:

SearchResult

Raises:

InvalidArgumentException – If a SearchRequest is provided. Use search() for a search request.

Examples

Note

Be sure to create a search index prior to executing search queries. Also, if an application desires to utilize search row locations, highlighting, etc. make sure the search index is setup appropriately. See Creating Indexes in Couchbase Server docs.

Simple search query:

import couchbase.search as search
from couchbase.options import SearchOptions

# ... other code ...

query = search.TermQuery('home')
q_res = scope.search_query('travel-sample-index',
                            query,
                            SearchOptions(limit=10))

for row in q_res.rows():
    print(f'Found row: {row}')

Simple search query with facets:

import couchbase.search as search
from couchbase.options import SearchOptions

# ... other code ...

facet_name = 'activity'
facet = search.TermFacet('activity')
query = search.TermQuery('home')
q_res = scope.search_query('travel-sample-index',
                            query,
                            SearchOptions(limit=10, facets={facet_name: facet}))

for row in q_res.rows():
    print(f'Found row: {row}')

print(f'facets: {q_res.facets()}')

Simple search query with fields and locations:

import couchbase.search as search
from couchbase.options import SearchOptions

# ... other code ...

search_fields = ['name', 'activity']
query = search.TermQuery('home')
q_res = scope.search_query('travel-sample-index',
                            query,
                            SearchOptions(limit=10,
                                        include_locations=True,
                                        fields=search_fields))

for row in q_res.rows():
    print(f'Found row: {row}')
    print(f'Fields: {row.fields}')
    print(f'Locations: {row.locations}')