run_sql_plus_plus_query
Execute a SQL++ query on a specified scope within the Couchbase MCP Server to retrieve results as a list of JSON objects for data interaction.
Instructions
Run a SQL++ query on a scope and return the results as a list of JSON objects.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| scope_name | Yes |
Implementation Reference
- src/tools/query.py:39-89 (handler)Core handler function that executes SQL++ queries against a Couchbase scope. Includes read-only mode validation using Lark SQL++ parser to prevent data/structure modifications. Connects to cluster/bucket/scope and iterates over query results.def run_sql_plus_plus_query( ctx: Context, bucket_name: str, scope_name: str, query: str ) -> list[dict[str, Any]]: """Run a SQL++ query on a scope and return the results as a list of JSON objects. The query will be run on the specified scope in the specified bucket. The query should use collection names directly without bucket/scope prefixes, as the scope context is automatically set. Example: query = "SELECT * FROM users WHERE age > 18" # Incorrect: "SELECT * FROM bucket.scope.users WHERE age > 18" """ cluster = get_cluster_connection(ctx) bucket = connect_to_bucket(cluster, bucket_name) app_context = ctx.request_context.lifespan_context read_only_query_mode = app_context.read_only_query_mode logger.info(f"Running SQL++ queries in read-only mode: {read_only_query_mode}") try: scope = bucket.scope(scope_name) results = [] # If read-only mode is enabled, check if the query is a data or structure modification query if read_only_query_mode: parsed_query = parse_sqlpp(query) data_modification_query = modifies_data(parsed_query) structure_modification_query = modifies_structure(parsed_query) if data_modification_query: logger.error("Data modification query is not allowed in read-only mode") raise ValueError( "Data modification query is not allowed in read-only mode" ) if structure_modification_query: logger.error( "Structure modification query is not allowed in read-only mode" ) raise ValueError( "Structure modification query is not allowed in read-only mode" ) # Run the query if it is not a data or structure modification query result = scope.query(query) for row in result: results.append(row) return results except Exception as e: logger.error(f"Error running query: {e!s}", exc_info=True) raise
- src/tools/__init__.py:35-50 (registration)The run_sql_plus_plus_query tool is registered by being included in the ALL_TOOLS list, which is used to register all Couchbase MCP tools with the server.ALL_TOOLS = [ get_buckets_in_cluster, get_server_configuration_status, test_cluster_connection, get_scopes_and_collections_in_bucket, get_collections_in_scope, get_scopes_in_bucket, get_document_by_id, upsert_document_by_id, delete_document_by_id, get_schema_for_collection, run_sql_plus_plus_query, get_index_advisor_recommendations, list_indexes, get_cluster_health_and_services, ]
- src/tools/__init__.py:17-21 (registration)Import of the run_sql_plus_plus_query function from query.py submodule for exposure and registration.# Query tools from .query import ( get_schema_for_collection, run_sql_plus_plus_query, )