Skip to main content

Data Service Admin Interface

The Django Admin interface provides a powerful GUI for managing Apps, DataSources, and DataTables. This guide covers all administrative features.

Accessing the Admin​

URL​

https://your-domain.com/admin/

Login​

Use your superuser or staff account credentials.

App Administration​

App List View​

Location: Admin → App → Apps

Features:

  • List Display: Name, slug, datasource count, active status, creation date, creator
  • Filters: Active status, creation date
  • Search: Name, slug, description
  • Actions: Bulk operations on selected apps

Columns:

  • Name: App name
  • Slug: URL-safe identifier (auto-generated)
  • Datasources: Clickable link showing count
  • Is Active: Active/inactive status
  • Created At: Timestamp
  • Created By: User who created the app

Creating an App​

  1. Click "Add App" button

  2. Fill in the form:

    • Name (required): Application name
    • Slug (auto-filled): URL-safe identifier
    • Description (optional): Documentation
    • Is Active: Checkbox (default: checked)

  3. Click "Save" to create

Notes:

  • Slug is auto-generated from name using slugify
  • User tracking (created_by, modified_by) is automatic

Editing an App​

  1. Click on app name in list
  2. Modify fields
  3. Click "Save" or "Save and continue editing"

Field Sections:

Basic Information

  • Name
  • Slug (read-only after creation)
  • Description

Status

  • Is Active

Statistics (collapsed by default)

  • Datasource Count: Link to datasources
  • Table Count: Total across all datasources

Metadata (collapsed by default)

  • Created At (read-only)
  • Updated At (read-only)
  • Created By (read-only)
  • Modified By (read-only)

Deleting an App​

Soft Delete:

  • Use the admin to mark is_active = False
  • Also marks all datasources and datatables as inactive

Hard Delete:

  • Use the "Delete" button
  • Cascades to all datasources and datatables
  • Warning: This is permanent!

DataSource Administration​

DataSource List View​

Location: Admin → Data → Data sources

Features:

  • List Display: Name, slug, app link, provider type, table count, active status, creation date
  • Filters: Provider type, active status, creation date, app
  • Search: Name, slug, description, app name
  • Actions: Bulk operations

Columns:

  • Name: DataSource name
  • Slug: URL identifier
  • App: Clickable link to parent app
  • Provider Type: flat_table, jsonb, or mongodb
  • Tables: Clickable count linking to tables
  • Is Active: Status indicator
  • Created At: Timestamp

Creating a DataSource​

  1. Click "Add Data source" button

  2. Fill in the form:

    • App (required): Select parent app
    • Name (required): DataSource name
    • Slug (auto-filled): URL-safe identifier
    • Description (optional): Documentation
    • Provider Type (required): Choose from dropdown
    • Provider Config (optional): JSON configuration
    • Is Active: Checkbox

  3. Click "Save" to create

Provider Types:

  • Flat PostgreSQL Tables: Traditional SQL tables
  • PostgreSQL JSONB: JSON document storage
  • MongoDB Collections: MongoDB integration

Provider Config Example:

{
  "compression": "lz4",
  "indexing": "gin",
  "custom_options": {
    "buffer_size": 8192
  }
}

Viewing Provider Config​

The admin shows two versions of provider_config:

  • Editable JSON: Raw JSON input
  • Formatted Display: Pretty-printed, read-only view

DataSource Details​

Field Sections:

Basic Information

  • App (dropdown)
  • Name
  • Slug (prepopulated from name)
  • Description

Provider Configuration

  • Provider Type (dropdown)
  • Provider Config (JSON editor)
  • Provider Config Display (formatted, read-only)

Status

  • Is Active

Statistics (collapsed)

  • Table Count: Link to tables
  • Materialized: Shows "X / Y" format

Metadata (collapsed)

  • Timestamps and user tracking

DataTable Administration​

DataTable List View​

Location: Admin → Data → Data tables

Features:

  • List Display: Name, datasource, app, field count, materialization status, active status, creation date
  • Filters: Materialization status, active status, creation date, app, datasource
  • Search: Name, description, physical table name, datasource name, app name
  • Actions: Bulk operations

Columns:

  • Name: Table name (used in API URLs)
  • DataSource: Link to parent datasource
  • App: Link to app
  • Fields: Count of fields in schema
  • Is Materialized: Whether physical table exists
  • Is Active: Status indicator
  • Created At: Timestamp

Creating a DataTable​

  1. Click "Add Data table" button

  2. Fill in the form:

    • DataSource (required): Select parent datasource
    • Name (required): Table name
    • Description (optional): Documentation
    • JSON Schema (required): Frictionless Table Schema
    • Is Materialized: Checkbox
    • Is Active: Checkbox

  3. Click "Save" to create

JSON Schema Input:

Use the JSON editor to define your Frictionless Table Schema:

{
  "fields": [
    {
      "name": "id",
      "type": "integer",
      "constraints": {
        "required": true,
        "unique": true
      }
    },
    {
      "name": "email",
      "type": "string",
      "format": "email",
      "constraints": {
        "required": true
      }
    }
  ],
  "primaryKey": ["id"]
}

Validation:

  • Schema is validated on save
  • Invalid schemas show error messages
  • Field types and constraints are checked

DataTable Details​

Field Sections:

Basic Information

  • DataSource (dropdown)
  • Name
  • Description

Frictionless Table Schema

  • JSON Schema: Editable JSON field
  • JSON Schema Display: Formatted, read-only view with syntax highlighting
  • Help text: "Define table structure using Frictionless Table Schema format"

Physical Storage (collapsed)

  • Physical Table Name (auto-generated, read-only)
  • Is Materialized (checkbox)

Schema Metadata (collapsed)

  • Schema Hash (SHA256, read-only)
  • Field Count (calculated, read-only)
  • Field Names (comma-separated list, read-only)

Status

  • Is Active

Metadata (collapsed)

  • Timestamps and user tracking

Schema Display Features​

The admin provides multiple views of the schema:

  1. Editable JSON: For creating/updating
  2. Formatted Display: Pretty-printed with scrolling
  3. Field Analysis: Extracted field names and count
  4. Hash Tracking: For cache invalidation

Physical Table Name​

Auto-generated format: {app_name}_{table_name}

Example:

  • App: "My Application"
  • Table: "users"
  • Physical: "my_application_users"

The name is sanitized (spaces → underscores, lowercase).

Schema Operation Administration​

SchemaOperation List View​

Location: Admin → Data → Schema operations

Features:

  • List Display: Operation type, status, datasource, table, timestamps
  • Filters: Operation type, status, datasource, creation date
  • Search: Datasource name, table name, error message
  • Read-Only: Operations are created by the system

Columns:

  • Operation Type: CREATE_TABLE, ALTER_TABLE, DROP_TABLE
  • Status: PENDING, IN_PROGRESS, SUCCESS, FAILED, ROLLED_BACK
  • DataSource: Link to datasource
  • Table: Link to table (if applicable)
  • Started At: When operation began
  • Completed At: When operation finished
  • Created At: When operation was logged

Viewing Operation Details​

Field Sections:

Operation Info

  • DataSource (link)
  • Table (link)
  • Operation Type
  • Status

Operation Details (collapsed)

  • Raw JSON: Operation parameters
  • Formatted Display: Pretty-printed view

SQL Commands (collapsed)

  • Executed SQL: The SQL that was run
  • Executed SQL Display: Formatted with syntax highlighting
  • Rollback SQL: SQL to undo the operation
  • Rollback SQL Display: Formatted view

Execution Tracking (collapsed)

  • Started At
  • Completed At
  • Error Message (if failed)

Metadata (collapsed)

  • Creation timestamp and user

Operation Status Flow​

PENDING → IN_PROGRESS → SUCCESS
                      ↓
                   FAILED → ROLLED_BACK (optional)

Admin Tips & Best Practices​

1. Search Functionality​

Quick Search:

  • Apps: Search by name, slug, description
  • DataSources: Search by name, slug, app name
  • DataTables: Search across name, datasource, app

2. Filtering​

Use filters to narrow down results:

Active apps only → Filter: Is Active = Yes
Recent datasources → Filter: Created At = Today
Materialized tables → Filter: Is Materialized = Yes

3. Bulk Operations​

Select multiple items and choose an action:

  • Mark as inactive (soft delete)
  • Hard delete (careful!)
  • Export selected

4. Navigation​

Quick navigation via clickable links:

  • App → DataSources → DataTables
  • Datasource counts link to filtered datasource list
  • Table counts link to filtered table list

5. JSON Editing​

Tips for JSON Schema editing:

  • Use a JSON validator before pasting
  • Check the formatted display after saving
  • Validation errors appear at the top of the form
  • Keep a backup before major schema changes

6. Audit Trail​

Every record tracks:

  • Created At / Created By
  • Updated At / Modified By
  • Assigned To (if applicable)

Use this for compliance and debugging.

7. Schema Operations Log​

Monitor the SchemaOperation model for:

  • Failed operations
  • Performance issues
  • Rollback history
  • Audit compliance

Common Admin Tasks​

Task 1: Create Complete Data Structure​

  1. Create App

    • Navigate to App admin
    • Add new app with name and description

  2. Create DataSource

    • Go to DataSource admin
    • Select the app
    • Choose provider type
    • Configure provider settings

  3. Create DataTable

    • Go to DataTable admin
    • Select the datasource
    • Define Frictionless schema
    • Save and verify

Task 2: Update Existing Schema​

  1. Find the DataTable in admin
  2. Click to edit
  3. Modify the json_schema field
  4. Save
  5. Check that schema_hash updated
  6. Review SchemaOperation log for changes

Task 3: Deactivate Resources​

Soft Delete (Recommended):

  1. Edit the resource
  2. Uncheck "Is Active"
  3. Save

Benefits:

  • Preserves data
  • Can be restored
  • Maintains referential integrity

From App:

  • Click datasource count → filtered datasource list

From DataSource:

  • Click table count → filtered table list

From DataTable:

  • Click datasource link → datasource details
  • Click app link → app details

Task 5: Troubleshoot Schema Issues​

  1. Check DataTable admin for validation errors
  2. Review SchemaOperation admin for failed operations
  3. Check error messages in operation details
  4. Verify Frictionless schema format
  5. Test schema in API docs before admin save

Keyboard Shortcuts​

Django admin provides shortcuts:

  • Ctrl+S / Cmd+S: Save
  • Escape: Close popup
  • Tab: Navigate fields
  • Arrow Keys: Navigate dropdowns

Mobile Access​

The Jazzmin theme provides responsive admin:

  • Works on tablets and phones
  • Touch-friendly interface
  • Collapsible sidebars
  • Optimized for small screens

Permissions​

Required Permissions​

App Management:

  • app.add_app
  • app.change_app
  • app.delete_app
  • app.view_app

DataSource Management:

  • data.add_datasource
  • data.change_datasource
  • data.delete_datasource
  • data.view_datasource

DataTable Management:

  • data.add_datatable
  • data.change_datatable
  • data.delete_datatable
  • data.view_datatable

Granting Permissions​

  1. Go to Users admin
  2. Select user
  3. In "User permissions" section:
    • Search for app/data permissions
    • Add to "Chosen permissions"
  4. Save

Or create a Group with permissions:

  1. Go to Groups admin
  2. Create group (e.g., "Data Managers")
  3. Add all data service permissions
  4. Assign users to the group

Security Considerations​

  1. Limit Admin Access: Only grant to trusted users
  2. Use Groups: Manage permissions via groups
  3. Audit Regularly: Review SchemaOperation logs
  4. Backup Before Changes: Especially schema updates
  5. Test in Development: Validate changes before production
  6. Monitor User Activity: Check user tracking fields

Troubleshooting​

Problem: Can't save DataTable​

Solution:

  • Check schema validation errors at top of form
  • Verify JSON syntax is correct
  • Ensure required fields are present
  • Check field type names match Frictionless spec

Problem: Slug already exists​

Solution:

  • Each slug must be unique within its scope
  • Apps: Globally unique slugs
  • DataSources: Unique within app
  • DataTables: Unique within datasource
  • Manually specify a different slug

Problem: Schema hash not updating​

Solution:

  • Ensure you're actually changing the json_schema field
  • Save the form (hash updates on save)
  • Check if save was successful
  • Review any error messages

Next Steps​