← Back to demos

GA4 BigQuery Analytics

Query the Google Analytics 4 public dataset using AILANG — with contract-verified SQL generation, capability budgets, and ADC authentication.

CLI Contracts WASM-ready

GA4 Analytics Dashboard — AILANG ecommerce demo showing BigQuery queries, SQL generation, and chart visualization

The React dev UI — contract-verified SQL generation with live BigQuery results

⚡

14 Pre-built Queries

Events, products, revenue, funnel, device, geo, session metrics — all type-checked and contract-verified

🔒

Capability Budgets

FS and Net effects are budget-limited: max 30 FS ops, 20 Net calls per run

✅

Contract Verification

Every query ensures result starts with SELECT and is >50 characters

🛠

ADC Authentication

Uses Application Default Credentials — no API keys to manage

Quick Start

Clone the repo and run the BigQuery demo with your GCP credentials:

# 1. Clone the repo
git clone https://github.com/sunholo-data/ailang-demos
cd ailang-demos

# 2. Authenticate with GCP (one-time)
gcloud auth application-default login

# 3. Run the BigQuery demo
GOOGLE_API_KEY="" ailang run --entry main --caps IO,FS,Net \
  ecommerce/bigquery_demo.ail
  

The demo queries the public GA4 ecommerce dataset on BigQuery. Your GCP project is auto-detected from gcloud config and used for job billing only — the dataset itself is public.

REST API & Protocol Server

Serve all AILANG modules as a REST API with auto-generated OpenAPI, MCP, and A2A endpoints — zero code changes required:

# Start the API server (with AI stub for testing)
ailang serve-api --port 8092 --mcp-http --caps IO,AI,FS,Net --ai-stub \
  ecommerce/contracts_demo.ail \
  ecommerce/services/ga4_queries.ail \
  ecommerce/services/bigquery.ail \
  ecommerce/services/gcp_auth.ail \
  ecommerce/api/handlers.ail \
  ecommerce/data/products.ail \
  ecommerce/services/recommendations.ail
  

Every export func becomes a POST endpoint. All protocol endpoints are auto-generated from the same AILANG source.

API Documentation

OpenAPI ReDoc — auto-generated API reference from AILANG type signatures

ReDoc — auto-generated from AILANG’s Hindley-Milner type signatures

📖

Swagger UI

/api/_meta/docs — interactive, try-it-out API explorer (like FastAPI)

📑

ReDoc

/api/_meta/redoc — clean read-only API reference

🔬

OpenAPI 3.1

/api/_meta/openapi.json — raw spec for code generation

🛡

Health Check

/api/_health — module count and export count

Protocol Endpoints

Protocol	Endpoint	Description
MCP	POST /mcp/	MCP Streamable HTTP (tools/list, tools/call)
A2A	POST /a2a/	Agent-to-Agent JSON-RPC task execution
A2A	GET /.well-known/agent.json	A2A Agent Card (37 skills)
REST	POST /api/{module}/{func}	Direct function invocation

Connect as MCP Server

Add AILANG as an MCP server in Claude Desktop, Cursor, or any MCP client:

# claude_desktop_config.json
{
  "mcpServers": {
    "ailang-ecommerce": {
      "command": "ailang",
      "args": [
        "serve-api", "--mcp",
        "--caps", "IO,AI,FS,Net",
        "--ai-stub",
        "ecommerce/contracts_demo.ail",
        "ecommerce/services/ga4_queries.ail",
        "ecommerce/services/bigquery.ail",
        "ecommerce/services/gcp_auth.ail",
        "ecommerce/api/handlers.ail",
        "ecommerce/data/products.ail",
        "ecommerce/services/recommendations.ail"
      ]
    }
  }
}
  

Use --mcp for stdio transport (Claude Desktop) or --mcp-http for HTTP transport (remote clients). All 37 exported functions appear as MCP tools with auto-generated JSON Schema from AILANG types.

Other Run Modes

# AI product recommendations (needs Gemini)
ailang run --entry main --caps IO,AI --ai gemini-2-5-flash \
  ecommerce/main.ail

# Trusted analytics with budget-as-contract
ailang run --entry main --caps IO,FS,Net \
  ecommerce/trusted_analytics_demo.ail

# Run inline tests (14 queries, all contract-verified)
ailang test ecommerce/services/ga4_queries.ail

# With contract verification
ailang run --entry main --caps IO --verify-contracts \
  ecommerce/contracts_demo.ail
  

Available Queries

Function	Description	Args
topEventsQuery	Top events by count	limit: int
eventCountsByDateQuery	Event counts for date range	start, end: string
eventTrendQuery	Single event trend over time	eventName: string
topProductsByRevenueQuery	Top products by revenue	limit: int
revenueByCategoryQuery	Revenue by product category	—
purchaseFunnelQuery	View → cart → checkout → purchase	—
topCategoriesByViewsQuery	Top categories by page views	limit: int
deviceBreakdownQuery	Users by device type	—
geoDistributionQuery	Users by country	limit: int
browserBreakdownQuery	Users by browser	—
sessionMetricsQuery	Users, events, sessions, purchases	—
dailySummaryQuery	Daily summary with key metrics	start, end: string

Prerequisites

You need AILANG installed and GCP credentials configured:

# Install AILANG
brew install sunholo-data/tap/ailang

# Authenticate with GCP
gcloud auth application-default login

# Verify
ailang version
gcloud auth application-default print-access-token | head -c 20
  

Dataset: bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*
Source: github.com/sunholo-data/ailang-demos/tree/main/ecommerce