Combined Queries

Combined queries are alice's differentiator. Any tool can show you MRR from Stripe. alice shows you MRR from Stripe alongside login activity from Supabase, correlated by customer email, with action buttons to do something about it -- all from a single /alice command in Slack.

Why Combined Queries

Single-source queries tell you what happened. Combined queries tell you why it happened and what to do about it.

Consider churn risk. A single-source Stripe query can show you customers with failed payments. That is useful, but incomplete. A combined query can show you customers who have both a failed payment in Stripe and no login activity in your app for 14 days. That is actionable intelligence -- those customers are genuinely at risk, not just hitting a temporary card issue.

Here is how single-source and combined queries compare for common use cases:

The combined version gives you context that drives action. Instead of a list of names, you get a prioritized list with the data needed to make a decision.

How Combined Queries Work

When a combined skill executes, alice follows this process:

Step 1: Parallel Execution

alice sends queries to all configured sources simultaneously. For a skill querying both Stripe and Supabase, both queries start at the same time. This keeps execution fast -- the total time is roughly equal to the slowest individual query, not the sum of all queries.

Step 2: Result Collection

Each source returns its results independently. alice waits for all sources to complete before proceeding.

For example:

• Stripe returns a list of customers with failed payments: email, amount, failure reason, date
• Supabase returns user activity data: email, last login, session count, plan

Step 3: In-Memory Join

alice joins the results in memory using the join key you defined when creating the skill. The join key is a field that exists in both result sets -- typically email, customer_id, or another unique identifier.

The join operation works like a SQL INNER JOIN: only records that have a matching value in both result sets appear in the combined output. If a Stripe customer does not have a matching row in Supabase (or vice versa), that record is excluded.

Step 4: Combined Output

The joined results are formatted according to your output configuration and delivered to Slack. Fields from both sources are available in the combined result, so you can display Stripe revenue data alongside Supabase user data in a single table or list.

Creating a Combined Skill

Step 1: Select Multiple Sources

In the skill builder, select Combined as the query mode. This is available when you have two or more connected sources.

The Combined mode selector shows all your connected sources. Check the sources you want to include in the query.

Step 2: Configure Per-Source Queries

After selecting sources, the builder shows a query configuration section for each source. Configure each independently:

For Stripe sources:

• Select a metric block or API endpoint
• Configure time period, parameters, and limits
• The same options as a standalone Stripe skill

For Supabase sources:

• Use the Visual Builder or Raw SQL
• Select tables, columns, filters, and sort order
• The same options as a standalone Supabase skill

Each source query is independent. Think of them as two separate queries that will be joined by a common key.

Step 3: Define the Join Key

The join key is the field used to match records across sources. Choose a field that exists in both result sets and uniquely identifies a record.

Common join keys:

The join key configuration lets you specify the field name in each source's results. They do not need to have the same column name -- only the same values. For example, the Stripe result might have a field called customer and the Supabase result might have a field called email, but both contain the same email addresses.

Step 4: Configure Combined Output

After defining the join, configure the output format. You have access to fields from all sources:

• In a Table output, add columns from Stripe (e.g., mrr, payment_status) and Supabase (e.g., last_login, session_count) side by side.
• In a List output, use a Stripe field as the title and Supabase fields as details, or vice versa.
• In a Summary output, show aggregate values from both sources.

The test panel works with combined queries too. Click "Test query" to run both source queries, see the join result, and verify the combined output before saving.

Examples

Churn Risk (Stripe + Supabase)

Identifies customers who are at genuine risk of churning by combining payment failure signals from Stripe with inactivity signals from your application.

Stripe query: Failed payments or past-due subscriptions in the last 30 days. Returns email, payment_status, failure_reason, amount.

Supabase query: Users with no login in the last 14 days. Returns email, last_login, session_count_30d, plan.

Join key: email

Combined result in Slack:

3 accounts at high churn risk:

jane@acme.com -- Payment failed, no login 18 days
  Amount: $99/mo | Failure: card_declined | Sessions: 0
  [Tag in Stripe] [Open in Stripe]

bob@startup.io -- Past due, 2 sessions this month
  Amount: $39/mo | Failure: past_due | Sessions: 2
  [Tag in Stripe] [Open in Stripe]

carol@bigco.com -- Payment failed, no login 7 days
  Amount: $99/mo | Failure: insufficient_funds | Sessions: 0
  [Tag in Stripe] [Open in Stripe]

Expansion Ready (Stripe + Supabase)

Finds customers who are on a lower-tier plan but are actively using your product at a rate that suggests they would benefit from upgrading.

Stripe query: Active subscriptions on the starter/free plan. Returns email, plan, mrr, subscription_start.

Supabase query: Users who have exceeded 80% of their plan's usage limits. Returns email, usage_count, limit, feature_most_used.

Join key: email

Combined result: A list of customers ripe for an upsell conversation, complete with their current plan, usage metrics, and how long they have been a customer.

VIP Users (Stripe + Supabase)

Enriches high-revenue Stripe customers with application data so you know who your most valuable users are and how they use your product.

Stripe query: Top customers by lifetime revenue (using vip_customers metric block with limit of 20). Returns email, name, total_revenue, currency.

Supabase query: User details including team size, last login, and account creation date. Returns email, team_size, last_login, created_at.

Join key: email

Combined result: A ranked list of VIP customers with their revenue, team size, activity recency, and tenure. Useful for account management, retention outreach, and case study identification.

Trial Health (Stripe + Supabase)

Monitors trial users to identify who is likely to convert and who needs a nudge before their trial expires.

Stripe query: Subscriptions in trial status expiring in the next 7 days. Returns email, trial_end, days_left.

Supabase query: Feature adoption for trial users -- number of key features used, onboarding completion percentage, and total sessions. Returns email, features_used, onboarding_pct, sessions.

Join key: email

Combined result: Trial users sorted by conversion likelihood. Users with high feature adoption are likely to convert; users with low adoption and expiring trials need outreach.

Best Practices

Choose the Right Join Key

The join key determines how well your combined query works. Follow these guidelines:

• Use email when both sources reliably have the same email address for each user. This is the most common approach.
• Use a stored ID (like stripe_customer_id in your Supabase database) for a more reliable match. Emails can change; IDs do not.
• Avoid join keys with low match rates. If only 20% of your Stripe customers have a matching row in Supabase, 80% of Stripe results will be dropped. Consider whether a single-source query with manual correlation might be more useful.

Keep Individual Queries Focused

Each source query in a combined skill should return only the data needed for the combined result. Broad queries that return thousands of rows from each source will slow down the in-memory join. Use filters, limits, and specific column selections to keep result sets manageable.

Use Parameters for Flexibility

Add parameters so users can adjust the combined query without editing it. Common patterns:

• --days=14 to control the inactivity threshold in the Supabase query
• --limit=20 to control how many results the Stripe query returns
• --plan=pro to filter by plan in either source

Parameters work the same way in combined queries as in single-source skills. See Parameters for details.

Test Before Deploying

The test panel in the skill builder runs the full combined query pipeline: parallel source execution, join, and output formatting. Always test with realistic parameters before saving, especially for queries that will run on a schedule and post to a Slack channel.

Plan Requirements

Combined queries require the Pro plan ($39/month) or Business plan ($99/month). The Free plan supports single-source queries only.

Each execution of a combined query counts as one query against your plan limit, regardless of how many sources it queries.

See Plans and Pricing for full plan details.

Troubleshooting

Empty Results After Join

If your combined query returns no results, the join key likely has no matches between the two result sets:

• Check field names. The join key field must exist in both source results. Run each source query individually with the test panel to verify the field names.
• Check field values. The values must match exactly. "jane@acme.com" in Stripe must be exactly "jane@acme.com" in Supabase -- case matters.
• Broaden filters. If one source query returns very few results, the join will produce even fewer. Try removing filters to see if matches exist at all.

Slow Combined Queries

Combined queries can be slower than single-source queries because they run multiple queries and join the results:

• Add limits. Cap each source query to a reasonable number of rows (e.g., 100-500).
• Use indexed columns. For Supabase queries, make sure filtered columns have database indexes.
• Simplify Stripe queries. Use metric blocks instead of raw API calls when possible -- they are pre-optimized.

"Combined queries require Pro plan"

This message appears if your workspace is on the Free plan. Upgrade to Pro ($39/month) or Business ($99/month) from Dashboard > Settings > Billing. See Plans and Pricing.

Next Steps

• Create a Skill -- Full walkthrough of the skill builder (including combined mode)
• AI Skill Generation -- alice can generate combined skills from natural language descriptions
• Skill Templates -- Pre-built templates to install as starting points
• Connect Stripe -- Connect your Stripe account (one side of the combined query)
• Connect Supabase -- Connect your Supabase project (the other side)
• Parameters -- Add dynamic inputs to your combined queries
• Scheduled Reports -- Run combined queries on a schedule
• Plans and Pricing -- Plan requirements for combined queries