Scope

class acouchbase.scope.AsyncScope(bucket: AsyncBucket, scope_name: str)

Create a Couchbase Scope instance.

Exposes the operations which are available to be performed against a scope. Namely the ability to access to Collections for performing operations.

Parameters:
  • bucket (Bucket) – A Bucket instance.

  • scope_name (str) – Name of the scope.

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

Executes an analaytics query against the scope.

Note

The analytics query is executed lazily in that it is executed once iteration over the AsyncAnalyticsResult 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 AsyncAnalyticsResult which provides access to iterate over the analytics query results and access metadata and metrics about the analytics query.

Return type:

AsyncAnalyticsResult

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)
async for row in q_res.rows():
    print(f'Found row: {row}')

Simple analytics query with positional parameters:

from acouchbase.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]))
async for row in q_res.rows():
    print(f'Found row: {row}')

Simple analytics query with named parameters:

from acouchbase.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}))
async 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)
async 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) → AsyncCollection

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) → AsyncQueryResult

Executes a N1QL query against the scope.

Note

The query is executed lazily in that it is executed once iteration over the AsyncQueryResult 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 AsyncQueryResult which provides access to iterate over the query results and access metadata and metrics about the query.

Return type:

AsyncQueryResult

Examples

Simple query:

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

Simple query with positional parameters:

from acouchbase.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]))
async for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from acouchbase.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}))
async for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from acouchbase.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))
async 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]) → AsyncSearchResult

Executes an search against the scope.

Note

The search is executed lazily in that it is executed once iteration over the AsyncSearchResult 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 AsyncSearchResult which provides access to iterate over the search query results and access metadata and metrics about the search query.

Return type:

AsyncSearchResult

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 acouchbase.options import SearchOptions

# ... other code ...

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

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

Simple vector search:

import couchbase.search as search
from acouchbase.options import SearchOptions
from acouchbase.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))

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

Combine search and vector search:

import couchbase.search as search
from acouchbase.options import SearchOptions
from acouchbase.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))

async 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]) → AsyncSearchResult

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 AsyncSearchResult 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 AsyncSearchResult which provides access to iterate over the search query results and access metadata and metrics about the search query.

Return type:

AsyncSearchResult

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 acouchbase.options import SearchOptions

# ... other code ...

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

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

Simple search query with facets:

import couchbase.search as search
from acouchbase.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}))

async 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 acouchbase.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))

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

alias of AsyncScope