playbooks

home / skills / materializeinc / materialize / markdown-docs

markdown-docs skill

/doc/user/static/markdown-docs

This skill helps you understand Materialize queries, sources, sinks, and views by summarizing key concepts from the official docs.

npx playbooks add skill materializeinc/materialize --skill markdown-docs

Review the files below or copy the command above to add this skill to your agents.

Files (407)
SKILL.md
6.8 KB
---
name: materialize-docs
description: Materialize documentation for SQL syntax, data ingestion, concepts, and best practices. Use when users ask about Materialize queries, sources, sinks, views, or clusters.
---

# Materialize Documentation

This skill provides comprehensive documentation for Materialize, a streaming database for real-time analytics.

## How to Use This Skill

When a user asks about Materialize:

1. **For SQL syntax/commands**: Read files in the `sql/` directory
2. **For core concepts**: Read files in the `concepts/` directory
3. **For data ingestion**: Read files in the `ingest-data/` directory
4. **For transformations**: Read files in the `transform-data/` directory

## Documentation Sections

### Administrations

- **Usage (Self-Managed)**: `administration/usage/index.md`
- **Usage & billing (Cloud)**: `administration/billing/index.md`

### Concepts
Learn about the core concepts in Materialize.

- **Namespaces**: `concepts/namespaces/index.md`
- **Clusters**: `concepts/clusters/index.md`
- **Indexes**: `concepts/indexes/index.md`
- **Reaction Time, Freshness, and Query Latency**: `concepts/reaction-time/index.md`
- **Sinks**: `concepts/sinks/index.md`
- **Sources**: `concepts/sources/index.md`
- **Views**: `concepts/views/index.md`

### Ingest data
Best practices for ingesting data into Materialize from external systems.

- **Amazon EventBridge**: `ingest-data/webhooks/amazon-eventbridge/index.md`
- **AWS PrivateLink connections (Cloud-only)**: `ingest-data/network-security/privatelink/index.md`
- **CockroachDB CDC using Kafka and Changefeeds**: `ingest-data/cdc-cockroachdb/index.md`
- **Debezium**: `ingest-data/debezium/index.md`
- **Fivetran**: `ingest-data/fivetran/index.md`
- **HubSpot**: `ingest-data/webhooks/hubspot/index.md`
- **Kafka**: `ingest-data/kafka/index.md`
- **MongoDB**: `ingest-data/mongodb/index.md`
- **Monitoring data ingestion**: `ingest-data/monitoring-data-ingestion/index.md`
- **MySQL**: `ingest-data/mysql/index.md`
- _(and 12 more files in this section)_

### Manage Materialize

- **Appendix: Alternative cluster architectures**: `manage/appendix-alternative-cluster-architectures/index.md`
- **Disaster recovery (Cloud)**: `manage/disaster-recovery/index.md`
- **Monitoring and alerting**: `manage/monitor/index.md`
- **Operational guidelines**: `manage/operational-guidelines/index.md`
- **Use dbt to manage Materialize**: `manage/dbt/index.md`
- **Use Terraform to manage Materialize**: `manage/terraform/index.md`

### Materialize console
Introduction to the Materialize Console, user interface for Materialize

- **Admin (Cloud-only)**: `console/admin/index.md`
- **Clusters**: `console/clusters/index.md`
- **Connect (Cloud-only)**: `console/connect/index.md`
- **Create new**: `console/create-new/index.md`
- **Database object explorer**: `console/data/index.md`
- **Integrations**: `console/integrations/index.md`
- **Monitoring**: `console/monitoring/index.md`
- **SQL Shell**: `console/sql-shell/index.md`
- **User profile**: `console/user-profile/index.md`

### Overview
Learn how to efficiently transform data using Materialize SQL.

- **Dataflow troubleshooting**: `transform-data/dataflow-troubleshooting/index.md`
- **FAQ: Indexes**: `transform-data/faq/index.md`
- **Idiomatic Materialize SQL**: `transform-data/idiomatic-materialize-sql/index.md`
- **Optimization**: `transform-data/optimization/index.md`
- **Patterns**: `transform-data/patterns/index.md`
- **Troubleshooting**: `transform-data/troubleshooting/index.md`

### Security

- **Appendix**: `security/appendix/index.md`
- **Cloud**: `security/cloud/index.md`
- **Self-managed**: `security/self-managed/index.md`

### Self-Managed Deployments
Learn about the key components and architecture of self-managed Materialize deployments.

- **Appendix**: `self-managed-deployments/appendix/index.md`
- **Deployment guidelines**: `self-managed-deployments/deployment-guidelines/index.md`
- **FAQ**: `self-managed-deployments/faq/index.md`
- **Installation**: `self-managed-deployments/installation/index.md`
- **Materialize CRD Field Descriptions**: `self-managed-deployments/materialize-crd-field-descriptions/index.md`
- **Materialize Operator Configuration**: `self-managed-deployments/operator-configuration/index.md`
- **Self-managed release versions**: `self-managed-deployments/release-versions/index.md`
- **Troubleshooting**: `self-managed-deployments/troubleshooting/index.md`
- **Upgrading**: `self-managed-deployments/upgrading/index.md`

### Serve results
Serving results from Materialize

- **`SELECT` and `SUBSCRIBE`**: `serve-results/query-results/index.md`
- **Sink results**: `serve-results/sink/index.md`
- **Use BI/data collaboration tools**: `serve-results/bi-tools/index.md`
- **Use foreign data wrapper (FDW)**: `serve-results/fdw/index.md`

### SQL commands
SQL commands reference.

- **Namespaces**: `sql/namespaces/index.md`
- **ALTER CLUSTER**: `sql/alter-cluster/index.md`
- **ALTER CLUSTER REPLICA**: `sql/alter-cluster-replica/index.md`
- **ALTER CONNECTION**: `sql/alter-connection/index.md`
- **ALTER DATABASE**: `sql/alter-database/index.md`
- **ALTER DEFAULT PRIVILEGES**: `sql/alter-default-privileges/index.md`
- **ALTER INDEX**: `sql/alter-index/index.md`
- **ALTER MATERIALIZED VIEW**: `sql/alter-materialized-view/index.md`
- **ALTER NETWORK POLICY (Cloud)**: `sql/alter-network-policy/index.md`
- **ALTER ROLE**: `sql/alter-role/index.md`
- _(and 112 more files in this section)_

### Tools and integrations
Get details about third-party tools and integrations supported by Materialize

- **Client libraries**: `integrations/client-libraries/index.md`
- **Connect to Materialize via HTTP**: `integrations/http-api/index.md`
- **Connect to Materialize via WebSocket**: `integrations/websocket-api/index.md`
- **Connection Pooling**: `integrations/connection-pooling/index.md`
- **Foreign data wrapper (FDW) **: `integrations/fdw/index.md`
- **MCP Server**: `integrations/llm/index.md`
- **mz - Materialize CLI**: `integrations/cli/index.md`
- **mz-debug**: `integrations/mz-debug/index.md`
- **SQL clients**: `integrations/sql-clients/index.md`

## Quick Reference

### Common SQL Commands

| Command | Description |
|---------|-------------|
| `CREATE SOURCE` | Connect to external data sources (Kafka, PostgreSQL, MySQL) |
| `CREATE MATERIALIZED VIEW` | Create incrementally maintained views |
| `CREATE INDEX` | Create indexes on views for faster queries |
| `CREATE SINK` | Export data to external systems |
| `SELECT` | Query data from sources, views, and tables |

### Key Concepts

- **Sources**: Connections to external data systems that stream data into Materialize
- **Materialized Views**: Views that are incrementally maintained as source data changes
- **Indexes**: Arrangements of data in memory for fast point lookups
- **Clusters**: Isolated compute resources for running dataflows
- **Sinks**: Connections that export data from Materialize to external systems

Overview

This skill provides concise, practical documentation for Materialize: a streaming SQL database for real-time analytics. It covers SQL syntax, data ingestion, core concepts, cluster management, and best practices for building incrementally maintained views and low-latency queries. Use it to get targeted guidance on queries, sources, sinks, views, and operational tasks.

How this skill works

The skill inspects organized documentation by topic: SQL command reference, concepts, ingestion patterns, transformations, and operational guidance. For SQL questions it consults the SQL directory; for concepts it reads the concepts pages; for ingestion and transform workflows it reads the ingest-data and transform-data sections. It synthesizes examples, common commands, and practical steps for real deployments.

When to use it

  • You need correct Materialize SQL syntax or examples for CREATE SOURCE, CREATE MATERIALIZED VIEW, CREATE SINK, SELECT, or CREATE INDEX.
  • You plan to ingest change data capture (CDC) or streaming data from Kafka, Debezium, MySQL, PostgreSQL, MongoDB, or webhooks.
  • You want guidance on clusters, namespaces, replicas, or self-managed vs cloud deployments.
  • You need patterns for low-latency, incrementally maintained analytics or view optimization.
  • You are troubleshooting dataflow, monitoring ingestion, or preparing disaster recovery and upgrades.

Best practices

  • Prefer CREATE MATERIALIZED VIEW for frequently queried aggregations to get incremental updates and low latency.
  • Create indexes on materialized views for hot lookup paths rather than indexing raw sources.
  • Ingest via CDC connectors (Debezium, Postgres/MySQL connectors) to preserve change semantics for consistent views.
  • Monitor freshness and reaction time; set alerts on lag metrics and stalled dataflows.
  • Use namespaces and clusters to isolate workloads and enforce resource boundaries in production.

Example use cases

  • Build a real-time dashboard with a materialized view that aggregates events from Kafka and serves SELECT and SUBSCRIBE queries.
  • Stream CDC from MySQL via Debezium into Materialize, create views for business metrics, and export results to a downstream sink.
  • Optimize a slow analytical query by adding an index on a materialized view instead of scanning raw streaming tables.
  • Deploy a self-managed Materialize cluster with operator configuration and upgrade guidelines for production.

FAQ

Can Materialize handle change data capture from databases?

Yes. Materialize supports CDC workflows via connectors like Debezium and native Kafka sources to ingest row-level changes reliably.

When should I use a materialized view vs a regular view?

Use a materialized view when you need incremental maintenance and low-latency read performance for repeated queries; use a regular view for ad-hoc or lightweight transformations.