Skip to main content
Converting workloads from another platform to pipelines is an iterative process. The quality of your results depends on how well you prepare your source files, the guidance you give , and how you refine that guidance over time. This guide covers preparing your source files, writing effective conversion guidance, reviewing the analysis before you build, and iterating to improve results.

​
Prepare your source files

How you provide your workload files affects both the flexibility of the conversion process and the quality of the result.

​
Choose the right file loading method

Before selecting files, check that they don’t contain passwords, secrets, or other sensitive information. Your files are processed by an LLM service that does not use customer data for model training, but you are responsible for ensuring your files are safe to share before proceeding.
offers two ways to provide workload files: Git repository files and Upload files. For supported workload types, the dialog filters the file selector to show only the accepted file types for that platform. The Git repository files option is the recommended approach. It gives you more flexibility—especially if your organization uses a connected Git provider—and allows to revisit your source files during conversion. To use this option, add your workload files to your Git repository before you open the Convert workloads with Maia dialog. The Upload files option is a convenient alternative for smaller workloads, but has stricter limits: up to 10 files per upload, a combined size of 20 MB, and a 10 MB limit per individual file. If your workloads exceed these limits, use Git repository files instead.

​
Convert from an unsupported platform

If your source platform isn’t listed under Workload type, select Other. Your workload files must be in a text-based format—such as XML, JSON, or SQL—even if they use a proprietary file extension. For example, some platforms package XML files in a ZIP archive with a custom extension; can process these files as long as the underlying content is text-based. Not all unsupported platforms use text-based formats. Some use binary formats that can’t process this way. If you’re unsure whether your platform stores workloads in a text-based format, contact your Matillion account team before attempting a conversion.
The Other option doesn’t filter file types, so make sure you select files that match your intended workload. Selecting the wrong files won’t produce an error—it will simply produce a poor conversion.

​
Write effective conversion guidance

The conversions/user-guidance.md file is the most important tool for improving conversion quality. Providing a context file is optional, but conversions are typically more successful when has additional guidance to work from. reads this file every time it builds converted pipelines on your branch, so it accumulates value the more you develop it. It also uses any other context files that already exist in your repository. On your first conversion, this file doesn’t exist yet—it’s created after your first run. Leave it empty the first time and focus on reviewing what produces. As you identify patterns in how interprets your workloads, add specific instructions. Useful guidance includes:
  • Naming conventions for pipelines and components
  • Schema and table mapping rules
  • Design preferences or standards specific to your organization
  • Source platform logic that should be preserved or adapted in a particular way
You can edit this file at Step 3 of the conversion dialog, or directly in the file system at any time outside the dialog.
Be as specific as possible. Broad instructions are less effective than targeted ones. For example, “always use lowercase and underscores for pipeline names” gives more to work with than “follow naming best practices.”

​
Review before you build

Detecting a misunderstanding here—before any pipelines exist—is more time-effective than correcting it afterward.

​
Read the workload analysis

After you submit your workload files, produces a natural language analysis describing everything it found. This analysis is written to the conversions/ folder and is available to review before any pipelines are built. Read this analysis carefully. If has misunderstood something or missed an element entirely, that affects the output. Look for:
  • Logic or components that appear to be missing from the analysis
  • Incorrect interpretations of source platform constructs
  • Table names and schema names that don’t match your source workload
The key references section of the conversion files is particularly useful for verifying that has extracted the correct table and schema names. If later uses incorrect schema references when building pipelines, check the key references first—if a schema name isn’t captured there, had no way to know about it.

​
Plan before building

When the analysis is complete, choose Plan conversion with Maia rather than beginning immediately. Planning gives you the opportunity to review ‘s intended approach, raise concerns, and request changes before any pipelines are built. Skipping the plan to see immediate results is a common mistake. Users who review and refine the plan typically spend less time correcting pipelines afterward.
Once you’ve worked through the planning stage and are consistently getting results you’re happy with, you can skip planning for similar workloads to speed up the conversion process.

​
Iterate to improve results

‘s outputs are non-deterministic, so the same workload can produce different results on different runs. This is expected. The goal is to develop guidance that consistently produces accurate results. When a conversion doesn’t meet your expectations:
  1. Identify specifically what went wrong—naming, logic, structure, or component selection.
  2. Update conversions/user-guidance.md with a targeted instruction that addresses the issue.
  3. Run the conversion again and compare the output.
  4. Repeat until produces the expected result consistently across multiple runs.
For example, if uses the wrong schema name, add a specific instruction rather than a general one:
  • Less effective: “Use the correct schema names.”
  • More effective: “All source tables are in the raw schema. Use staging as the target schema for all converted pipelines.”
The more specific your guidance, the more predictable your results will be over time.

​
SQL pass-through

SQL pass-through is available for the following workload types only:
  • IBM DataStage
  • Informatica IDMC
  • Informatica PowerCentre
  • Other
The SQL pass-through option in Advanced options lets you provide with the exact SQL from your source files. When you enable this option, analyzes the workload, describes it in natural language, and appends the raw SQL to the conversion files. This is useful when your source SQL contains specific constructs—such as non-standard joins or platform-specific formatting—that you want preserved. However, doesn’t automatically reproduce the SQL verbatim. To request exact reproduction, add an explicit instruction to conversions/user-guidance.md, for example: “Reproduce all SQL exactly as provided in the pass-through files.”