Grail Tables & Buckets

Grail Tables & Buckets

Grail organizes data in buckets (storage), tables (query targets), and views (filtered perspectives). Understanding this structure is key to writing efficient queries.

All Grail Tables

Table                    DQL Command              What It Contains
───────────────────────  ───────────────────────   ──────────────────────────
logs                     fetch logs                All log records
events                   fetch events              Davis events, custom, synthetic
metrics                  timeseries ...            All metric data points
spans                    fetch spans               Distributed trace spans
bizevents                fetch bizevents           Business events
security.events          fetch security.events     Vulnerability + attack findings
user.events              fetch user.events         RUM user events (New RUM)
user.sessions            fetch user.sessions       RUM sessions (New RUM)
user.replays             fetch user.replays        Session replay data
dt.system.events         fetch dt.system.events    System/self-monitoring events
dt.system.buckets        fetch dt.system.buckets   Bucket metadata
dt.entity.*              fetch dt.entity.host      Entity views (host, service, etc.)
dt.davis.problems        fetch dt.davis.problems   Davis-detected problems

Built-in Buckets

Bucket                              Table                  Retention
────────────────────────────────    ─────────────────────  ─────────
default_logs                        logs                   35 days
default_events                      events                 35 days
default_davis_events                events                 462 days
default_security_events             events                 1102 days (3 yr)
default_metrics                     metrics                462 days (15 mo)
default_spans                       spans                  10 days
default_bizevents                   bizevents              35 days
default_securityevents              security.events        372 days (1 yr)
default_securityevents_builtin      security.events        1102 days (3 yr)
default_user_events                 user.events            35 days
default_user_sessions               user.sessions          35 days

Discover Buckets

// List all buckets with retention
fetch dt.system.buckets
| fields name, dt.system.table, retention_days, records, estimated_uncompressed_bytes
| sort dt.system.table asc

Discover Fields (Schema)

// Show all fields for a table
describe logs
describe spans
describe dt.entity.host

// Semantic Dictionary — standardized field definitions
fetch dt.semantic_dictionary.models | filter data_object == "logs"
fetch dt.semantic_dictionary.models | filter data_object == "spans"

Custom Buckets

Create custom buckets for different retention periods or access control:

1. Settings → Storage management → + Bucket
2. Set name, table type (logs/events/spans), retention (10 days to 10 years)
3. Route data via OpenPipeline → Storage stage → Bucket assignment
4. Set permissions via IAM policy boundaries on bucket name

Query Cost Control

// Default: 1,000 records per query (append | limit N to change)
// Scan limit: controlled by scanLimitGBytes parameter (-1 = unlimited)
// Billing: DQL queries on logs/events consume DDUs based on data scanned

// Filter by bucket to reduce scan cost
fetch logs, from:now()-1h
| filter dt.system.bucket == "default_logs"
| limit 100

▶ Knowledge Check

Q: What's the default retention for spans?

• ❌ 35 days
• ✅ 10 days
• ❌ 462 days

Q: How do you discover all available fields for the logs table?

• ❌ fetch logs | fields *
• ✅ describe logs
• ❌ show schema logs