Tutorials¶

Tutorials are learning-oriented guides that help you master Duckalog through hands-on, step-by-step instruction. Each tutorial builds your skills progressively.

What are Tutorials?¶

Tutorials differ from how-to guides in their approach and purpose:

• Learning-oriented: Build understanding through guided practice
• Comprehensive: Cover concepts, not just steps
• Progressive: Each step builds on previous knowledge
• Beginner-friendly: Assume minimal prior knowledge

Available Tutorials¶

🟢 Getting Started with Duckalog¶

Complete Beginner Tutorial¶

Learn Duckalog from scratch with no prior experience.

What you'll build: - Basic Parquet data catalog - SQL transformations - Multi-source joins - Modular configuration with imports

Learning outcomes: - Understand Duckalog configuration structure - Create views over different data sources - Apply business logic with SQL - Organize configuration for maintainability

Prerequisites: - Basic Python knowledge - Familiarity with data files (CSV, Parquet) - No Duckalog experience required

Time commitment: 2-3 hours

🟡 Dashboard Basics Tutorial¶

Web UI Tutorial¶

Master the Duckalog web dashboard for interactive data exploration.

What you'll learn: - Dashboard installation and setup - View management and inspection - Ad-hoc querying - Configuration updates through UI - Data export capabilities

Learning outcomes: - Navigate the dashboard interface - Run queries and export results - Manage views and semantic models - Use dashboard for data discovery

Prerequisites: - Completed Getting Started tutorial OR - Basic Duckalog configuration knowledge - Web browser and basic web concepts

Time commitment: 1-2 hours

Tutorial Structure¶

Each tutorial follows this proven learning pattern:

Learning Objectives¶

Clear goals of what you'll accomplish.

Prerequisites¶

What you need to know before starting.

Step-by-Step Instructions¶

Guided learning with explanations and examples.

Check Your Understanding¶

Knowledge checks to reinforce learning.

Next Steps¶

Where to go after completing the tutorial.

Learning Path¶

For Complete Beginners¶

1. Start with Getting Started Tutorial
2. Learn core concepts and skills
3. Build your first complete catalog

4. Understand configuration patterns

5. Continue with Dashboard Tutorial

6. Apply your knowledge interactively
7. Learn data exploration techniques
8. Master the web interface

Outcome: You'll be comfortable with Duckalog fundamentals and ready for advanced topics.

For Experienced Users¶

If you already know similar tools:

1. Skim Getting Started Tutorial
2. Focus on Duckalog-specific concepts
3. Compare with your current workflow

4. Identify key differences

5. Jump to Dashboard Tutorial

6. Learn Duckalog's unique interface
7. Explore advanced features
8. Apply your existing knowledge

Tutorial vs How-to vs Reference¶

Tutorial Features¶

Hands-On Learning¶

• Real examples: Work with actual data files
• Progressive complexity: Start simple, build to advanced
• Immediate feedback: See results of each step
• Practical exercises: Apply concepts immediately

Clear Explanations¶

• Concept introduction: Learn the "why" behind each step
• Context and background: Understand when to use each feature
• Best practices: Learn industry-standard approaches
• Common pitfalls: Avoid typical beginner mistakes

Validation and Testing¶

• Knowledge checks: Test your understanding
• Practical verification: Ensure your solutions work
• Troubleshooting guidance: Fix common issues
• Success criteria: Know when you've mastered each skill

Getting the Most from Tutorials¶

Before You Start¶

1. Set up your environment with required software
2. Allocate sufficient time - don't rush through concepts
3. Prepare your workspace for focused learning
4. Check prerequisites to avoid frustration

During Learning¶

1. Follow steps sequentially - each builds on previous
2. Experiment with variations to deepen understanding
3. Take notes on concepts and insights
4. Test your knowledge with provided exercises

After Completing¶

1. Apply to your data to solidify learning
2. Explore related topics in how-to guides
3. Reference documentation for deeper details
4. Share your experience with the community

Prerequisites for All Tutorials¶

Technical Requirements¶

• Python 3.12+ installed and accessible
• Duckalog package installed:

  pip install duckalog
  

• Text editor or IDE for configuration files
• Command line/terminal for running commands

Optional but Helpful¶

• DuckDB CLI for direct database access
• Git for version control of your configurations
• Docker (for some advanced examples)

Data Files¶

All tutorials provide necessary data files or instructions to generate them. No external data sources required unless specifically mentioned.

Contributing Tutorials¶

Have an idea for a new tutorial? We welcome contributions!

Good Tutorial Characteristics:¶

• Learning-focused: Emphasizes understanding over quick solutions
• Progressive structure: Builds complexity gradually
• Complete examples: Provides all necessary files and data
• Tested approach: Steps verified to work correctly
• Clear explanations: Concepts explained before implementation

Tutorial Areas We Need:¶

• Advanced analytics techniques
• Enterprise deployment patterns
• Performance optimization deep-dive
• Integration with other tools
• **Custom extensions and plugins

Contribution Process:¶

1. Propose topic in GitHub discussions
2. Outline learning objectives and structure
3. Create draft tutorial following our template
4. Test with beginners to validate clarity
5. Submit pull request with complete materials

Getting Help¶

If you're stuck on a tutorial:

1. Re-read the current step carefully
2. Check the troubleshooting section for common issues
3. Verify your setup matches prerequisites
4. Review previous steps to ensure nothing was missed
5. Ask for help in GitHub discussions with specific details

When Asking for Help:¶

• Which tutorial and step you're on
• What you tried and what happened
• Your environment (OS, Python version, etc.)
• Error messages (full text, not paraphrased)
• Your configuration (sanitized if it contains secrets)

Next Steps After Tutorials¶

Once you've completed the tutorials:

1. Explore how-to guides for specific problems
2. Study reference documentation for complete knowledge
3. Work through examples for real-world patterns
4. Join the community to share and learn
5. Contribute back with your own tutorials and improvements

Ready to start learning? Choose a tutorial above and begin your Duckalog journey!