docs(connectors): add Looker Studio Data API + Columnar readmes

tutorial/markdown/connectors/looker-studio/columnar/readme.md

@@ -0,0 +1,120 @@
+---
+# frontmatter
+path: "/tutorial-looker-studio-columnar"
+# title and description do not need to be added to markdown, start with H2 (##)
+title: Looker Studio with Couchbase Columnar (Views-only)
+short_title: Columnar (Views-only)
+description:
+  - Connect Google Looker Studio to Couchbase Columnar using views only
+  - Create views in Capella and use them as stable, optimized datasets
+  - Learn authentication, configuration, schema inference, and troubleshooting
+content_type: tutorial
+filter: connectors
+technology:
+  - server
+  - query
+tags:
+  - Looker Studio
+  - Couchbase Columnar
+  - Connector
+  - Views-only
+sdk_language:
+  - javascript
+length: 20 Mins
+---
+
+<!-- [abstract] -->
+
+## Overview
+
+This is a views-only connector for Google Looker Studio and Couchbase Columnar. It exclusively accesses data through views in Couchbase Capella. Create one or more views first, then connect Looker Studio to those views for analysis.
+
+The connector authenticates with Basic Auth to the Columnar API (`/api/v1/request`) and infers schema automatically using `array_infer_schema` so Looker Studio fields are created with reasonable types.
+
+## Prerequisites
+
+- A Couchbase Columnar deployment reachable from Looker Studio.
+- A database user with permissions to read from the target Views/Collections and execute queries.
+- Network access from Looker Studio to your Columnar host.
+
+## Authentication
+
+When adding the data source, provide:
+
+- Path: The Columnar host (optionally with port). Examples:
+  - Capella-style host: `cb.<your-host>.cloud.couchbase.com`
+  - Self-managed: `my.host:18095` (port recommended if not 443)
+- Username and Password: Database credentials.
+
+The connector validates credentials by running a lightweight test query (`SELECT 1 AS test;`).
+
+## Create Views in Capella (Required)
+
+Before connecting, create views in Capella Columnar Workbench:
+
+1. Open Capella, navigate to the Columnar tab, and launch the Workbench for your cluster.
+2. Create a view using SQL++:
+
+```sql
+CREATE VIEW my_airports AS
+SELECT airportname, city, country
+FROM `travel-sample`.`inventory`.`airport`
+WHERE country = 'United States';
+```
+
+- Replace names as needed. Views are stable datasets optimized for BI.
+- For more, see the Couchbase docs on [Views and Tabular Views](https://docs.couchbase.com/columnar/sqlpp/5a_views.html) and on [Buckets, Scopes, and Collections](https://docs.couchbase.com/cloud/clusters/data-service/about-buckets-scopes-collections.html).
+
+## Configuration
+
+Choose your mode in the configuration screen:
+
+- Configuration Mode: `By View` (views-only connector).
+
+### Mode: By View
+
+- Couchbase Database, Scope, View: Selected from dropdowns populated from metadata.
+- Maximum Rows: Optional limit for returned rows; leave blank for no limit.
+
+What runs:
+
+- Data: `SELECT <requested fields or *> FROM \`database\`.\`scope\`.\`view\` [LIMIT n]`
+- Schema: `SELECT array_infer_schema((SELECT VALUE t FROM \`database\`.\`scope\`.\`view\` [LIMIT n])) AS inferred_schema;`
+
+> Note: This connector does not query collections directly and does not accept custom queries. It reads through views only.
+
+## Schema and Field Types
+
+- The connector converts inferred types to Looker types:
+  - number → NUMBER (metric)
+  - boolean → BOOLEAN (dimension)
+  - string/objects/arrays/null → STRING/TEXT (dimension)
+- Nested fields are flattened using dot and array index notation where possible (for example, `address.city`, `schedule[0].day`). Unstructured values may be stringified.
+
+## Data Retrieval
+
+- Only requested fields are projected. For nested fields, the connector fetches the required base fields and extracts values client-side.
+- Row limits:
+  - View mode: `Maximum Rows` controls `LIMIT` (blank = no limit).
+
+## Tips and Best Practices
+
+- Prefer views for BI tooling; they offer a stable, optimized interface.
+- Keep datasets scoped and use `LIMIT` while exploring.
+
+## Troubleshooting
+
+- Authentication failure: Check host/port, credentials, and network reachability to Columnar.
+- Schema inference errors: Ensure your entity or query returns rows; consider adding `LIMIT` for faster sampling.
+- API error from Columnar: Review the response message surfaced in Looker Studio and verify entity names, permissions, and syntax.
+
+## Future Scope (Prototype)
+
+- Collections and custom query support are in prototype and not available in this views-only connector. As support expands, you’ll be able to query collections directly from Looker Studio in addition to views.
+
+## Next Steps
+
+- Build charts in Looker Studio using your View- or Collection-backed fields.
+- Iterate on Views/queries to shape the dataset for analytics.
+
+

tutorial/markdown/connectors/looker-studio/dataapi/readme.md

@@ -0,0 +1,112 @@
+---
+# frontmatter
+path: "/tutorial-looker-studio-dataapi"
+# title and description do not need to be added to markdown, start with H2 (##)
+title: Looker Studio with Couchbase Data API
+short_title: Data API Connector
+description:
+  - Connect Google Looker Studio to Couchbase through the Data API
+  - Configure auth, select collections or use custom SQL++ queries
+  - Learn schema inference, limits, and troubleshooting tips
+content_type: tutorial
+filter: connectors
+technology:
+  - server
+  - query
+tags:
+  - Looker Studio
+  - Google Data Studio
+  - Data API
+  - Connector
+sdk_language:
+  - javascript
+length: 20 Mins
+---
+
+<!-- [abstract] -->
+
+## Overview
+
+Use this connector to build Looker Studio reports directly on Couchbase via the Data API. You can:
+
+- Query by selecting a specific `bucket.scope.collection`.
+- Or run a custom SQL++ query.
+
+Behind the scenes, the connector authenticates with Basic Auth and talks to the Data API endpoints for caller identity checks and to the Query Service for SQL++ execution. Schema is inferred automatically from sampled data to make fields available in Looker Studio.
+
+## Prerequisites
+
+- A Couchbase Capella cluster or a self-managed cluster with the Query Service reachable from Looker Studio.
+- A database user with permissions to read the target collections and run queries.
+- Network access from Looker Studio to your cluster host.
+
+## Authentication
+
+When you add the data source in Looker Studio, you will be prompted for:
+
+- Path: The cluster host (optionally with port). Examples:
+  - Capella: `cb.<your-host>.cloud.couchbase.com`
+  - Self-managed: `my.host:18095` (specify a non-443 port explicitly)
+- Username and Password: Database credentials.
+
+The connector validates credentials against the Data API (`/v1/callerIdentity`). If validation fails, verify host, port, credentials, and network access.
+
+## Configuration
+
+After authentication, choose a configuration mode:
+
+- Configuration Mode: `Query by Collection` or `Use Custom Query`.
+
+### Mode: Query by Collection
+
+- Couchbase Collection: Pick a `bucket > scope > collection` from the dropdown. The connector discovers collections for you.
+- Maximum Rows: Optional limit for returned rows (default 100).
+
+What runs:
+
+- Data: `SELECT RAW \`collection\` FROM \`bucket\`.\`scope\`.\`collection\` LIMIT <maxRows>`
+- Schema: `INFER \`bucket\`.\`scope\`.\`collection\` WITH {"sample_size": 100, "num_sample_values": 3, "similarity_metric": 0.6}`
+
+### Mode: Use Custom Query
+
+- Custom N1QL Query: Paste any valid SQL++ statement. Include a `LIMIT` for performance.
+
+What runs:
+
+- Schema inference first attempts: `INFER (<yourQuery [LIMIT 100 if absent]>) WITH {"sample_size": 10000, "num_sample_values": 2, "similarity_metric": 0.1}`
+- If that fails, it runs your query with `LIMIT 1` and infers the schema from one sample document.
+
+## Schema and Field Types
+
+- Fields are inferred from sampled data. Types map to Looker Studio as:
+  - NUMBER → metric
+  - BOOLEAN → dimension
+  - STRING (default for text, objects, arrays) → dimension
+- Nested fields use dot notation (for example, `address.city`). Arrays and objects not expanded become stringified values.
+- If the collection has no documents or your query returns no rows, schema inference will fail.
+
+## Data Retrieval
+
+- Only the fields requested by Looker Studio are returned. Nested values are extracted using dot paths where possible.
+- Row limits:
+  - Collection mode: `Maximum Rows` controls the `LIMIT` (default 100).
+  - Custom query mode: You control `LIMIT` inside your query.
+
+## Tips and Best Practices
+
+- Prefer `Query by Collection` for quick starts and simpler schemas.
+- Always add a `LIMIT` when exploring with custom queries.
+- Ensure your user has at least query and read access on the target collections.
+
+## Troubleshooting
+
+- Authentication error: Check host/port, credentials, and that the Data API is reachable from Looker Studio.
+- Empty schema or no fields: Ensure the collection has data; for custom queries, verify the statement and add `LIMIT` to improve sampling.
+- Query errors from the service: Review the error text surfaced in Looker Studio; fix syntax, permissions, or keyspace names.
+
+## Next Steps
+
+- Create charts and tables in Looker Studio from the exposed fields.
+- Iterate on custom SQL++ queries to shape the dataset for your dashboards.
+
+