Metadata Discovery

# List all views
curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.type == "view") | {name, description}'

# List all cubes
curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.type == "cube") | {name, description}'

curl -X GET "https://connect.squareup.com/reporting/v1/meta" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

{
  "cubes": [
    {
      "name": "Orders",
      "title": "Orders",
      "measures": [...],
      "dimensions": [...],
      "segments": [...]
    }
  ]
}

{
  "name": "Orders",
  "title": "Orders",
  "description": "Sales order data including payments, items, and fulfillment",
  "measures": [...],
  "dimensions": [...],
  "segments": [...]
}

{
  "name": "Orders.net_sales",
  "title": "Net Sales",
  "description": "Total sales after discounts and returns, excluding tax",
  "type": "number",
  "aggType": "sum",
  "drillMembers": ["Orders.order_id", "Orders.sale_timestamp"],
  "format": "currency"
}

{
  "name": "Orders.net_sales",
  "aggType": "sum"
}

{
  "name": "Orders.count",
  "aggType": "count"
}

{
  "name": "Orders.avg_net_sales",
  "aggType": "avg"
}

{
  "name": "Orders.location_id",
  "title": "Location ID",
  "description": "Unique identifier for the location where the order was placed",
  "type": "string",
  "suggestFilterValues": true
}

{
  "name": "Orders.location_id",
  "type": "string"
}

{
  "name": "Orders.sale_timestamp",
  "type": "time"
}

{
  "name": "Orders.local_date",
  "type": "time"
}

{
  "name": "Orders.closed_checks",
  "title": "Closed Checks",
  "description": "Filters to fully paid and settled orders, matching Sales Summary behavior"
}

{
  "filters": [{
    "member": "Orders.state",
    "operator": "equals",
    "values": ["COMPLETED"]
  }, {
    "member": "Orders.check_state",
    "operator": "equals",
    "values": ["CLOSED"]
  }]
}

{
  "segments": ["Orders.closed_checks"]
}

{
  "name": "Orders.net_sales",
  "title": "Net Sales",
  "type": "number",
  "aggType": "sum",
  "format": "currency",
  "meta": {
    "label": "Net sales",
    "tooltip": "Amount of gross sales minus discounts, comps, returns, refunds, tips, taxes, fees, or gift card sales.",
    "stability": "beta"
  }
}

{
  "name": "Orders.check_state",
  "title": "Check State",
  "type": "string",
  "meta": {
    "label": "Check state",
    "tooltip": "The payment status of the order.",
    "values": ["AWAITING_CAPTURE_CHECK", "CLOSED_CHECK", "OPEN_CHECK"]
  }
}

import requests
import os

def get_cube_measures(cube_name):
    """Fetch and parse measures from a specific cube."""

    response = requests.get(
        'https://connect.squareup.com/reporting/v1/meta',
        headers={'Authorization': f'Bearer {os.environ["SQUARE_ACCESS_TOKEN"]}'}
    )

    metadata = response.json()

    # Find the cube
    cube = next((c for c in metadata['cubes'] if c['name'] == cube_name), None)

    if not cube:
        raise ValueError(f"Cube {cube_name} not found")

    # Extract measure information
    measures = []
    for measure in cube['measures']:
        measures.append({
            'name': measure['name'],
            'title': measure['title'],
            'description': measure.get('description', ''),
            'type': measure['type'],
            'aggType': measure.get('aggType', 'unknown')
        })

    return measures

# Usage
measures = get_cube_measures('Orders')
for measure in measures:
    print(f"{measure['name']}: {measure['title']}")

async function buildDimensionSelector(cubeName) {
  const response = await fetch('https://connect.squareup.com/reporting/v1/meta', {
    headers: {
      'Authorization': `Bearer ${process.env.SQUARE_ACCESS_TOKEN}`
    }
  });

  const metadata = await response.json();
  const cube = metadata.cubes.find(c => c.name === cubeName);

  if (!cube) {
    throw new Error(`Cube ${cubeName} not found`);
  }

  // Build selector options
  return cube.dimensions.map(dimension => ({
    value: dimension.name,
    label: dimension.title,
    description: dimension.description,
    type: dimension.type
  }));
}

// Usage
const dimensions = await buildDimensionSelector('Orders');
console.log(dimensions);

def validate_query(query, metadata):
    """Validate that a query uses valid measures, dimensions, and segments."""

    cube_name = query.get('cube', 'Orders')
    cube = next((c for c in metadata['cubes'] if c['name'] == cube_name), None)

    if not cube:
        return False, f"Cube {cube_name} not found"

    # Validate measures
    valid_measures = {m['name'] for m in cube['measures']}
    for measure in query.get('measures', []):
        if measure not in valid_measures:
            return False, f"Invalid measure: {measure}"

    # Validate dimensions
    valid_dimensions = {d['name'] for d in cube['dimensions']}
    for dimension in query.get('dimensions', []):
        if dimension not in valid_dimensions:
            return False, f"Invalid dimension: {dimension}"

    # Validate segments
    valid_segments = {s['name'] for s in cube['segments']}
    for segment in query.get('segments', []):
        if segment not in valid_segments:
            return False, f"Invalid segment: {segment}"

    return True, "Query is valid"

# Usage
query = {
    "measures": ["Orders.net_sales"],
    "dimensions": ["Orders.location_id"],
    "segments": ["Orders.closed_checks"]
}

is_valid, message = validate_query(query, metadata)
print(f"Valid: {is_valid}, Message: {message}")

import time

class MetadataCache:
    def __init__(self, ttl_seconds=3600):
        self.cache = None
        self.last_fetch = 0
        self.ttl = ttl_seconds

    def get(self):
        now = time.time()
        if self.cache is None or (now - self.last_fetch) > self.ttl:
            self.cache = self._fetch_metadata()
            self.last_fetch = now
        return self.cache

    def _fetch_metadata(self):
        response = requests.get(
            'https://connect.squareup.com/reporting/v1/meta',
            headers={'Authorization': f'Bearer {os.environ["SQUARE_ACCESS_TOKEN"]}'}
        )
        return response.json()

    def invalidate(self):
        self.cache = None

# Usage
cache = MetadataCache(ttl_seconds=3600)  # 1 hour TTL
metadata = cache.get()

// Good: Dynamic
const measures = metadata.cubes.Orders.measures.map(m => ({
  label: m.title,
  value: m.name
}));

// Bad: Hard-coded
const measures = [
  { label: 'Net Sales', value: 'Orders.net_sales' },
  { label: 'Tips', value: 'Orders.tips_amount' }
];

# Validate first
is_valid, error = validate_query(query, metadata)
if not is_valid:
    raise ValueError(error)

# Then execute
results = execute_query(query)

{
  "measures": ["Orders.net_sales"],
  "segments": ["Orders.closed_checks"]
}

# app-requirements.yml
required_measures:
  - Orders.net_sales
  - Orders.tips_amount

required_dimensions:
  - Orders.location_id
  - Orders.sale_timestamp

required_segments:
  - Orders.closed_checks

curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.type == "view") | .name'

curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[].name'

curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.name == "Orders") | .measures[] | {name, title, description}'

curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.name == "Orders") | .dimensions[] | select(.type == "time") | .name'

curl -s -H "Authorization: Bearer $TOKEN" \
  https://connect.squareup.com/reporting/v1/meta | \
  jq '.cubes[] | select(.name == "Orders") | .segments[] | {name, title}'