Skip to main content

GraphQL API

Learn how to set up and use GraphQL to expose your data sources through a powerful, flexible API. Autonify automatically creates GraphQL endpoints for your databases, enabling easy integration with applications and AI tools.

VIDEO TUTORIAL⏱️ 2 min

📹 GraphQL Configuration Tutorial

Learn how to configure GraphQL integration in Autonify to expose your data sources through a powerful API for custom applications and integrations.

Overview​

Autonify's GraphQL integration provides:

  • Automatic API Generation: Instantly create GraphQL endpoints for your databases
  • Real-time Synchronization: Keep your API in sync with database changes
  • Interactive Playground: Test queries directly in the platform
  • Relationship Mapping: Automatically exposed foreign key relationships

Setting Up GraphQL​

Accessing GraphQL Configuration​

  1. Navigate to your Data Source from the Data Sources page
  2. Locate the Data Mesh Metadata agent in the agents section
  3. When configured, the agent shows two tabs:
    • API Status: Connection status and metrics
    • GraphQL Playground: Interactive query interface

Understanding the Data Mesh Metadata Agent​

The Data Mesh Metadata agent:

  • Configures and sets up your data mesh for the data source
  • Synchronizes all catalog metadata into a GraphQL instance
  • Automatically updates when scans are run
  • Can be run manually for ad-hoc synchronization

When not configured, you'll see:

  • Data Mesh Integration Required message
  • Run Data Mesh Integration button to set up the service

Synchronization Process​

Automatic Synchronization​

Every time a data source scan runs:

  1. The Data Mesh Metadata agent activates
  2. All catalog metadata is synchronized
  3. New tables and relationships are added
  4. The GraphQL schema is updated

Manual Synchronization​

To manually sync your data:

  1. Navigate to your data source
  2. Find the Data Mesh Metadata agent
  3. Click Run Agent button (appears when hovering over the agent card)
  4. The synchronization status will update

Using the GraphQL Playground​

Accessing the Playground​

  1. From your data source page
  2. Open the Data Mesh Metadata agent
  3. Click on the GraphQL Playground tab
  4. The interactive GraphQL interface opens

Writing Queries​

The playground allows you to:

  • Write and test GraphQL queries
  • Browse your schema with auto-completion
  • View query results in real-time
  • Save frequently used queries

Example Queries​

Simple Table Query​

query GetRecords {
  your_table_name(limit: 10) {
    id
    name
    created_at
  }
}

Query with Filters​

query FilteredQuery {
  your_table_name(
    where: {status: {_eq: "active"}}
    order_by: {created_at: desc}
  ) {
    id
    name
    status
  }
}

Query with Relationships​

query GetWithRelations {
  parent_table {
    id
    name
    # One-to-many relationship
    child_records {
      id
      description
    }
  }
}

Integration Benefits​

Quick Data Access​

  • Register your data source
  • Scan to discover schema
  • Automatically get a GraphQL API
  • Query data immediately

Third-Party Integration​

GraphQL endpoints can be integrated with:

  • AI Engines: Connect to LLMs and AI applications
  • Custom Applications: Build apps on your data
  • Analytics Tools: Enable data analysis
  • Reporting Systems: Create dynamic reports

API Features​

  • Type Safety: Strongly typed schema
  • Real-time Updates: Schema reflects database changes
  • Relationship Navigation: Follow foreign keys in queries
  • Flexible Queries: Request exactly what you need
  • Dynamic Authorization: Column-level permissions applied at query time
  • Data Firewall: Automatic filtering based on user permissions

Monitoring Synchronization​

Status Indicators​

The API Status tab displays:

Status Cards​

  • Connection Status: Active, Failed, or Not Configured
  • GraphQL Endpoint: Full URL with copy button
  • Last Sync: Timestamp of last synchronization
  • Metrics Summary: Tables, Relations, and Errors count

Detailed Sections​

  • Tables & Relationships:
    • Tables Tracked (GraphQL schema objects)
    • Relationships Created (Inter-table connections)
    • Tables Failed (if any)
  • Errors & Issues: Lists any synchronization problems

Cross-Source Foreign Keys​

When cross-source foreign keys exist:

  • A warning indicates they've been synced
  • Relationships span multiple databases
  • Unified querying across data sources

Best Practices​

Query Optimization​

  • Use field selection to minimize data transfer
  • Implement pagination for large datasets
  • Leverage relationships instead of multiple queries
  • Use query variables for reusable queries

Security & Authorization​

GraphQL uses the same authorization pattern as MCP servers:

Dynamic Role Generation​

  • Each user gets a unique, dynamically generated role at query time
  • Roles are created based on column-level permissions configured in the application
  • Permissions are cached in Redis for performance (24-hour TTL)

Column-Level Security​

  • Fine-grained access control at the column level
  • Permissions configured per table/column in the application
  • Automatic filtering of restricted columns from query results
  • Support for data masking and PII protection

Security Features​

  • Authentication: OAuth-based authentication via Supabase
  • Authorization: Dynamic roles with column-level permissions
  • Caching: Redis caching for high-performance permission checks
  • Audit Logging: All queries are logged for compliance
  • Rate Limiting: Prevents API abuse and ensures fair usage

Development Workflow​

  1. Discover: Scan your database to catalog schema
  2. Sync: Let the Mesh Metadata agent create the API
  3. Test: Use the playground to develop queries
  4. Integrate: Embed queries in your applications

Troubleshooting​

Synchronization Issues​

Tables not appearing in GraphQL:

  • Ensure the data source scan completed successfully
  • Check if the Data Mesh Metadata agent is configured (not showing "Data Mesh Integration Required")
  • If not configured, click Run Data Mesh Integration button
  • Manually run the agent using the Run Agent button to force synchronization
  • Verify table permissions in the source database

Relationships missing:

  • Confirm foreign keys exist in the database
  • Check if relationships were discovered during scan
  • Review the agent logs for mapping errors

Query errors:

  • Validate query syntax in the playground
  • Check field names match the schema
  • Ensure you have permission to access the data
  • Review error messages for specific issues

Performance Optimization​

For large databases:

  • Use query limits and pagination
  • Select only required fields
  • Index frequently queried columns
  • Monitor query execution time

Next Steps​

After setting up GraphQL:

  1. Learn about MCP Integration
  2. Configure data sources
  3. Manage teams