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.
- 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
AsyncAnalyticsResultbegins.See also
AnalyticsIndexManager: for how to manage analytics dataverses, datasets, indexes and links.analytics_query(): for how to execute cluster-level analytics queries
- 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; preferAnalyticsOptions(named_parameters=...), which cannot collide with an option name.
- Returns:
An instance of a
AsyncAnalyticsResultwhich provides access to iterate over the analytics query results and access metadata and metrics about the analytics query.- Return type:
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()}')
- collection(name: str) AsyncCollection
Creates a
Collectioninstance of the specified collection.- Parameters:
name (str) – Name of the collection to reference.
- Returns:
A
Collectioninstance of the specified collection.- Return type:
- eventing_functions() ScopeEventingFunctionManager
Get a manager for the eventing functions of this scope.
- Returns:
A
ScopeEventingFunctionManagerinstance.- Return type:
- 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
AsyncQueryResultbegins.Note
Scope-level queries are only supported on Couchbase Server versions that support scopes and collections.
See also
QueryIndexManager: For how to manage query indexes.query(): For how to execute cluster-level queries.
- 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; preferQueryOptions(named_parameters=...), which cannot collide with an option name.
- Returns:
An instance of a
AsyncQueryResultwhich provides access to iterate over the query results and access metadata and metrics about the query.- Return type:
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
AsyncSearchResultbegins.See also
ScopeSearchIndexManager: for how to manage search indexes.acouchbase.cluster.AsyncCluster.search(): for how to execute cluster-level search
- 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
SearchQueryis deprecated; wrap it withcreate()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
AsyncSearchResultwhich provides access to iterate over the search query results and access metadata and metrics about the search query.- Return type:
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
ScopeSearchIndexManagerinstance.- Return type:
- 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
AsyncSearchResultbegins.- 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
AsyncSearchResultwhich provides access to iterate over the search query results and access metadata and metrics about the search query.- Return type:
- Raises:
InvalidArgumentException – If a
SearchRequestis provided. Usesearch()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