canonical: https://jentic.com/apis/googleapis.com/bigquery

# Google BigQuery API

BigQuery is Google Cloud's serverless data warehouse for running SQL analytics over petabyte-scale datasets without managing infrastructure. The API exposes datasets, tables, jobs, models, routines, and row access policies so you can load data, run queries, stream inserts, schedule extracts, and manage ML routines from code. It supports federated queries across Cloud Storage, Bigtable, and external sources, and integrates with Google's IAM for fine-grained access control. Pricing is consumption-based on bytes scanned plus storage, with flat-rate reservations available for predictable workloads.

## For AI agents

Run SQL queries, manage datasets and tables, and orchestrate load/extract jobs in Google BigQuery. Agents can submit query jobs, page through results, and stream rows into tables.

## Scope

Does not handle Cloud Storage object management, Pub/Sub messaging, or Dataflow pipeline execution - use for warehouse query, load, and metadata operations only.

## Capabilities

- Submit asynchronous query jobs and poll their results through the jobs resource
- Create and update datasets, tables, and views with custom schemas and partitioning
- Stream rows into tables with insertAll for near-real-time analytics ingestion
- List and copy tables across datasets and projects for data sharing workflows
- Manage routines and BigQuery ML models for in-warehouse training and inference
- Apply row access policies and IAM bindings to enforce column- and row-level security
- Cancel running jobs and inspect job statistics for cost and performance tuning

## Use cases

### Ad-hoc Analytical Querying

Submit SQL queries against terabyte-to-petabyte datasets and stream paginated results back to an application. Jobs are submitted to /projects/{projectId}/queries or as insert jobs and resolved via /projects/{projectId}/jobs/{jobId}, with results pulled from /projects/{projectId}/queries/{jobId}/getQueryResults. Typical interactive queries return in seconds; long-running jobs can be polled or cancelled.

Example prompt: Submit a query job that selects the top 10 product_ids by sum(revenue) from project.dataset.orders for the last 7 days, poll until done, and return the rows.

### Pipeline Ingestion and Loading

Load batch files from Cloud Storage into managed tables and stream live events with insertAll. Load jobs are created at /projects/{projectId}/jobs with configuration.load, while streaming uses /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/insertAll. This supports ELT pipelines that land raw data, then transform it with scheduled query jobs.

Example prompt: Create a load job that ingests gs://bucket/events/2026-06-09/*.json into project.analytics.events with schema autodetect and WRITE_APPEND disposition.

### Dataset and Schema Governance

Create datasets per environment, apply IAM-based access controls, manage table schemas, and set retention and partitioning. Datasets are managed at /projects/{projectId}/datasets and tables at /projects/{projectId}/datasets/{datasetId}/tables, with patch operations for schema evolution. Combined with row access policies and labels, teams can enforce data governance at the warehouse layer.

Example prompt: Create dataset analytics_prod in US multi-region, then create a date-partitioned table events with the supplied JSON schema.

### BigQuery ML Model Management

Train, list, and delete BigQuery ML models and routines that run inference inside the warehouse. Models live under /projects/{projectId}/datasets/{datasetId}/models and routines under /projects/{projectId}/datasets/{datasetId}/routines. Useful for forecasting, classification, and embedding-generation directly on warehouse data without exporting it.

Example prompt: List all models in dataset analytics_prod and delete any model whose creation_time is older than 30 days.

### AI Agent Analytics Assistant

Connect an AI agent to BigQuery so business users can ask plain-English questions and receive validated results. The agent uses Jentic to discover the BigQuery query operation, generate SQL, submit a job, poll for completion, and format the response. Credentials stay in your Jentic One instance, so the agent never sees raw OAuth tokens.

Example prompt: Translate the user prompt 'how many signups did we get last week by country' into a BigQuery SQL job, run it, and return a table of country and count.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /projects/{+projectId}/queries | Run a SQL query and return results synchronously where possible |
| POST | /projects/{+projectId}/jobs | Submit a query, load, copy, or extract job |
| GET | /projects/{+projectId}/jobs/{+jobId} | Get the status and statistics of a job |
| POST | /projects/{+projectId}/datasets | Create a new dataset |
| POST | /projects/{+projectId}/datasets/{+datasetId}/tables | Create a new table in a dataset |
| POST | /projects/{+projectId}/datasets/{+datasetId}/tables/{+tableId}/insertAll | Stream rows into a table |
| GET | /projects/{+projectId}/datasets/{+datasetId}/tables/{+tableId} | Get a table's schema and metadata |

## Key resources

- **Datasets** — Create, list, patch, and delete datasets that group related tables and control access.
- **Tables** — Manage table schemas, partitioning, clustering, and stream rows via insertAll.
- **Jobs** — Submit query, load, copy, and extract jobs and poll for completion and statistics.
- **Models** — List and manage BigQuery ML models trained inside the warehouse.
- **Routines** — Manage user-defined functions and stored procedures.
- **Row Access Policies** — Define row-level filters that scope query results per user or group.

## Why Jentic

- **Setup:** Wiring the BigQuery API by hand means setting up Google OAuth2, granting a service identity the right warehouse scopes, and refreshing access tokens across its 42 query and load operations yourself. Through Jentic you install once, import the BigQuery API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** This API puts the project, dataset, and table in the URL path (/projects/{projectId}/datasets/{datasetId}/tables/{tableId}), so a rule can pin your agent to one project or dataset: it can run queries, load jobs, and stream rows there and nothing else. You choose the operations it may call, so you decide whether it can create datasets and tables or only read them.
- **Credential handling:** Your BigQuery OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a BigQuery query' or 'stream rows into BigQuery', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the discovery document.

## Related APIs

- **BigQuery Data Transfer API** — Schedules recurring loads from SaaS sources into BigQuery tables.
- **BigQuery Reservation API** — Manages BigQuery slot reservations and capacity commitments.
- **Snowflake API** — Cloud data warehouse with similar SQL analytics scope on a different vendor.

## FAQ

### What authentication does the BigQuery API use?

The BigQuery API uses Google OAuth 2.0 with scopes such as https://www.googleapis.com/auth/bigquery and https://www.googleapis.com/auth/cloud-platform. Jentic stores the OAuth client and refresh token in its encrypted vault and hands the agent a scoped access token at call time, so raw client secrets never enter agent context.

### Can I run SQL queries with the BigQuery API?

Yes. Submit a query job via POST /projects/{projectId}/queries for synchronous calls or POST /projects/{projectId}/jobs with a query configuration for long-running jobs, then poll GET /projects/{projectId}/jobs/{jobId} until status.state is DONE and read rows from getQueryResults.

### What are the rate limits for the BigQuery API?

BigQuery enforces project-level quotas rather than a per-second rate cap: typical limits include 100 concurrent interactive queries per project and 1,500 table operations per table per day. Streaming insertAll is capped at 1 GB per second per project. Check the Google Cloud quotas console for current values for your project.

### How do I stream rows into a BigQuery table through Jentic?

Search Jentic with 'stream rows into a BigQuery table', load the schema for POST /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/insertAll, and execute with the rows array. Jentic injects the OAuth token, so the agent only supplies projectId, datasetId, tableId, and the row payload.

### Is the BigQuery API free?

BigQuery offers a free tier of 1 TB of query data processed and 10 GB of storage per month; beyond that, you pay per byte scanned (on-demand) or via flat-rate slot reservations. Streaming inserts and most API operations are also metered. The API itself has no per-call surcharge.

### Can I cancel a long-running BigQuery query?

Yes, call POST /projects/{projectId}/jobs/{jobId}/cancel. The job moves to a cancelling state and any partial results are discarded; you are not billed for bytes scanned after cancellation propagates.

### Can I limit what my agent is allowed to do with the BigQuery API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which BigQuery operations and credentials the agent may use. Since the API carries the project, dataset, and table in the URL path (/projects/{projectId}/datasets/{datasetId}/tables/{tableId}), you can pin the agent to a single project or dataset so it runs queries, submits load jobs, and streams rows there and nowhere else. You also choose the exact operations it can call, so you decide whether it may create datasets and tables or only read from them and query existing data.