Bigquery Port

Purpose

This is the Harbor reference integration for the BigQuery API.

Use it when:

• building BigQuery actions in Harbor
• extending the Dock / Hub BigQuery entry
• teaching Codex or OpenClaw how to map a data platform API into Harbor Ports and Harbor Actions without turning Harbor into a generic SQL transport

Harbor Port worksheet

Product

• Product: BigQuery API
• Publisher slug: google
• Publisher name: Google
• Category: Data
• Tags: google, bigquery, data, analytics, sql

Safe Harbor Port metadata

• Kind: http_api
• Label: BigQuery API
• Description: BigQuery API connection managed locally through Harbor.
• Base URL: https://bigquery.googleapis.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

BigQuery is a good Harbor fit when we stay on project-scoped routes and treat SQL execution as an approval-friendly action.

Good Harbor BigQuery actions:

• stable GET routes for dataset inventory and job inspection
• one explicit POST route for synchronous query execution
• Action Model input.path, input.query, and input.body envelopes instead of freeform URL editing
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for the bounded query request body
• resultMode: "json_summary" for all starter actions

Avoid for now:

• load jobs and upload flows
• table mutation surfaces
• arbitrary multi-endpoint SQL orchestration
• automatic publish of SQL execution actions

Starter BigQuery actions

Automatic read actions

• list-datasets -> GET /bigquery/v2/projects/{projectId}/datasets
• get-job -> GET /bigquery/v2/projects/{projectId}/jobs/{jobId}

Approval-friendly write or execute actions

• run-query -> POST /bigquery/v2/projects/{projectId}/queries

Why these actions

These routes fit Harbor's current safe model because they:

• stay under one fixed BigQuery API origin
• use explicit project-scoped path parameters that operators supply at execution time
• keep optional query parameters typed and reviewable
• expose SQL execution as a named capability instead of arbitrary HTTP or raw credential access
• keep hidden auth entirely local to Harbor Node

Action Model notes

For BigQuery actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /bigquery/v2/projects/{projectId}/datasets
• /bigquery/v2/projects/{projectId}/queries
• /bigquery/v2/projects/{projectId}/jobs/{jobId}

At execution time, callers supply values by location:

• input.path for path placeholders
• input.query for typed query parameters
• input.body for JSON request bodies

Example dataset listing request:

{
  "path": {
    "projectId": "my-analytics-project"
  },
  "query": {
    "maxResults": 25
  }
}

Example job inspection request:

{
  "path": {
    "projectId": "my-analytics-project",
    "jobId": "job_xYz123"
  },
  "query": {
    "location": "US"
  }
}

Example query request:

{
  "path": {
    "projectId": "my-analytics-project"
  },
  "body": {
    "query": "SELECT CURRENT_DATE() AS today",
    "useLegacySql": false,
    "maxResults": 100
  }
}

Harbor fills path placeholders safely, validates query values against the stored schema, and keeps the request URL Harbor-owned.

Safety note for SQL execution

run-query stays on require_approval because BigQuery SQL can do more than reads. Depending on the request body and project permissions, queries may create tables, write results, or run DML and DDL statements. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the BigQuery Dock entry from Dock / Hub.
2. Configure the local Google bearer token in Harbor Node with the BigQuery scopes you need.
3. Use list-datasets first to confirm the port is working.
4. Use get-job to inspect known jobs before introducing broader query workflows.
5. Keep run-query on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing BigQuery Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path or bounded path-template actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden BigQuery auth
• widen BigQuery into a generic arbitrary SQL or HTTP proxy

Current update strategy

For now, BigQuery updates are manual:

• update the Dock / Hub BigQuery integration document in apps/hub/catalog/integrations/google/bigquery.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as richer table-scoped actions or provider-side SQL templating are intentionally deferred until Harbor has clearer policy controls for data-writing operations.

Official reference starting points

• BigQuery REST root: https://docs.cloud.google.com/bigquery/docs/reference/rest
• Datasets list: https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list
• Jobs get: https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/get
• Jobs query: https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query