Skip to content

Commit f872209

Browse files
teetanghteetangh
committed
docs(connectors): add Looker Studio Data API + Columnar readmes; mark Columnar as views-only and add Capella view setup
- Add detailed Data API readme: PATH_USER_PASS auth, collection vs custom SQL++ modes, schema inference (INFER + fallback), limits, troubleshooting - Rewrite Columnar readme as views-only: required Capella view creation steps with SQL++ example, links to docs; remove collection/custom query modes; add future scope note (collections prototype) - Standardize tutorial frontmatter across both readmes Files: - couchbase-tutorials/tutorial/markdown/connectors/looker-studio/dataapi/readme.md - couchbase-tutorials/tutorial/markdown/connectors/looker-studio/columnar/readme.md
1 parent 4d03c3b commit f872209

File tree

2 files changed

+232
-0
lines changed

2 files changed

+232
-0
lines changed

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
# frontmatter
3+
path: "/tutorial-looker-studio-columnar"
4+
# title and description do not need to be added to markdown, start with H2 (##)
5+
title: Looker Studio with Couchbase Columnar (Views-only)
6+
short_title: Columnar (Views-only)
7+
description:
8+
- Connect Google Looker Studio to Couchbase Columnar using views only
9+
- Create views in Capella and use them as stable, optimized datasets
10+
- Learn authentication, configuration, schema inference, and troubleshooting
11+
content_type: tutorial
12+
filter: connectors
13+
technology:
14+
- server
15+
- query
16+
tags:
17+
- Looker Studio
18+
- Couchbase Columnar
19+
- Connector
20+
- Views-only
21+
sdk_language:
22+
- javascript
23+
length: 20 Mins
24+
---
25+
26+
<!-- [abstract] -->
27+
28+
## Overview
29+
30+
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.
31+
32+
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.
33+
34+
## Prerequisites
35+
36+
- A Couchbase Columnar deployment reachable from Looker Studio.
37+
- A database user with permissions to read from the target Views/Collections and execute queries.
38+
- Network access from Looker Studio to your Columnar host.
39+
40+
## Authentication
41+
42+
When adding the data source, provide:
43+
44+
- Path: The Columnar host (optionally with port). Examples:
45+
- Capella-style host: `cb.<your-host>.cloud.couchbase.com`
46+
- Self-managed: `my.host:18095` (port recommended if not 443)
47+
- Username and Password: Database credentials.
48+
49+
The connector validates credentials by running a lightweight test query (`SELECT 1 AS test;`).
50+
51+
## Create Views in Capella (Required)
52+
53+
Before connecting, create views in Capella Columnar Workbench:
54+
55+
1. Open Capella, navigate to the Columnar tab, and launch the Workbench for your cluster.
56+
2. Create a view using SQL++:
57+
58+
```sql
59+
CREATE VIEW my_airports AS
60+
SELECT airportname, city, country
61+
FROM `travel-sample`.`inventory`.`airport`
62+
WHERE country = 'United States';
63+
```
64+
65+
- Replace names as needed. Views are stable datasets optimized for BI.
66+
- 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).
67+
68+
## Configuration
69+
70+
Choose your mode in the configuration screen:
71+
72+
- Configuration Mode: `By View` (views-only connector).
73+
74+
### Mode: By View
75+
76+
- Couchbase Database, Scope, View: Selected from dropdowns populated from metadata.
77+
- Maximum Rows: Optional limit for returned rows; leave blank for no limit.
78+
79+
What runs:
80+
81+
- Data: `SELECT <requested fields or *> FROM \`database\`.\`scope\`.\`view\` [LIMIT n]`
82+
- Schema: `SELECT array_infer_schema((SELECT VALUE t FROM \`database\`.\`scope\`.\`view\` [LIMIT n])) AS inferred_schema;`
83+
84+
> Note: This connector does not query collections directly and does not accept custom queries. It reads through views only.
85+
86+
## Schema and Field Types
87+
88+
- The connector converts inferred types to Looker types:
89+
- number → NUMBER (metric)
90+
- boolean → BOOLEAN (dimension)
91+
- string/objects/arrays/null → STRING/TEXT (dimension)
92+
- Nested fields are flattened using dot and array index notation where possible (for example, `address.city`, `schedule[0].day`). Unstructured values may be stringified.
93+
94+
## Data Retrieval
95+
96+
- Only requested fields are projected. For nested fields, the connector fetches the required base fields and extracts values client-side.
97+
- Row limits:
98+
- View mode: `Maximum Rows` controls `LIMIT` (blank = no limit).
99+
100+
## Tips and Best Practices
101+
102+
- Prefer views for BI tooling; they offer a stable, optimized interface.
103+
- Keep datasets scoped and use `LIMIT` while exploring.
104+
105+
## Troubleshooting
106+
107+
- Authentication failure: Check host/port, credentials, and network reachability to Columnar.
108+
- Schema inference errors: Ensure your entity or query returns rows; consider adding `LIMIT` for faster sampling.
109+
- API error from Columnar: Review the response message surfaced in Looker Studio and verify entity names, permissions, and syntax.
110+
111+
## Future Scope (Prototype)
112+
113+
- 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.
114+
115+
## Next Steps
116+
117+
- Build charts in Looker Studio using your View- or Collection-backed fields.
118+
- Iterate on Views/queries to shape the dataset for analytics.
119+
120+

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
# frontmatter
3+
path: "/tutorial-looker-studio-dataapi"
4+
# title and description do not need to be added to markdown, start with H2 (##)
5+
title: Looker Studio with Couchbase Data API
6+
short_title: Data API Connector
7+
description:
8+
- Connect Google Looker Studio to Couchbase through the Data API
9+
- Configure auth, select collections or use custom SQL++ queries
10+
- Learn schema inference, limits, and troubleshooting tips
11+
content_type: tutorial
12+
filter: connectors
13+
technology:
14+
- server
15+
- query
16+
tags:
17+
- Looker Studio
18+
- Google Data Studio
19+
- Data API
20+
- Connector
21+
sdk_language:
22+
- javascript
23+
length: 20 Mins
24+
---
25+
26+
<!-- [abstract] -->
27+
28+
## Overview
29+
30+
Use this connector to build Looker Studio reports directly on Couchbase via the Data API. You can:
31+
32+
- Query by selecting a specific `bucket.scope.collection`.
33+
- Or run a custom SQL++ query.
34+
35+
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.
36+
37+
## Prerequisites
38+
39+
- A Couchbase Capella cluster or a self-managed cluster with the Query Service reachable from Looker Studio.
40+
- A database user with permissions to read the target collections and run queries.
41+
- Network access from Looker Studio to your cluster host.
42+
43+
## Authentication
44+
45+
When you add the data source in Looker Studio, you will be prompted for:
46+
47+
- Path: The cluster host (optionally with port). Examples:
48+
- Capella: `cb.<your-host>.cloud.couchbase.com`
49+
- Self-managed: `my.host:18095` (specify a non-443 port explicitly)
50+
- Username and Password: Database credentials.
51+
52+
The connector validates credentials against the Data API (`/v1/callerIdentity`). If validation fails, verify host, port, credentials, and network access.
53+
54+
## Configuration
55+
56+
After authentication, choose a configuration mode:
57+
58+
- Configuration Mode: `Query by Collection` or `Use Custom Query`.
59+
60+
### Mode: Query by Collection
61+
62+
- Couchbase Collection: Pick a `bucket > scope > collection` from the dropdown. The connector discovers collections for you.
63+
- Maximum Rows: Optional limit for returned rows (default 100).
64+
65+
What runs:
66+
67+
- Data: `SELECT RAW \`collection\` FROM \`bucket\`.\`scope\`.\`collection\` LIMIT <maxRows>`
68+
- Schema: `INFER \`bucket\`.\`scope\`.\`collection\` WITH {"sample_size": 100, "num_sample_values": 3, "similarity_metric": 0.6}`
69+
70+
### Mode: Use Custom Query
71+
72+
- Custom N1QL Query: Paste any valid SQL++ statement. Include a `LIMIT` for performance.
73+
74+
What runs:
75+
76+
- Schema inference first attempts: `INFER (<yourQuery [LIMIT 100 if absent]>) WITH {"sample_size": 10000, "num_sample_values": 2, "similarity_metric": 0.1}`
77+
- If that fails, it runs your query with `LIMIT 1` and infers the schema from one sample document.
78+
79+
## Schema and Field Types
80+
81+
- Fields are inferred from sampled data. Types map to Looker Studio as:
82+
- NUMBER → metric
83+
- BOOLEAN → dimension
84+
- STRING (default for text, objects, arrays) → dimension
85+
- Nested fields use dot notation (for example, `address.city`). Arrays and objects not expanded become stringified values.
86+
- If the collection has no documents or your query returns no rows, schema inference will fail.
87+
88+
## Data Retrieval
89+
90+
- Only the fields requested by Looker Studio are returned. Nested values are extracted using dot paths where possible.
91+
- Row limits:
92+
- Collection mode: `Maximum Rows` controls the `LIMIT` (default 100).
93+
- Custom query mode: You control `LIMIT` inside your query.
94+
95+
## Tips and Best Practices
96+
97+
- Prefer `Query by Collection` for quick starts and simpler schemas.
98+
- Always add a `LIMIT` when exploring with custom queries.
99+
- Ensure your user has at least query and read access on the target collections.
100+
101+
## Troubleshooting
102+
103+
- Authentication error: Check host/port, credentials, and that the Data API is reachable from Looker Studio.
104+
- Empty schema or no fields: Ensure the collection has data; for custom queries, verify the statement and add `LIMIT` to improve sampling.
105+
- Query errors from the service: Review the error text surfaced in Looker Studio; fix syntax, permissions, or keyspace names.
106+
107+
## Next Steps
108+
109+
- Create charts and tables in Looker Studio from the exposed fields.
110+
- Iterate on custom SQL++ queries to shape the dataset for your dashboards.
111+
112+

0 commit comments

Comments
 (0)