1. How SQAI Searches Confluence
A common misconception is that when you connect Confluence, SQAI downloads and "memorizes" your entire instance. For enterprise environments with thousands of pages and constant updates, this would be inefficient and create security risks regarding stale data.
Instead, SQAI performs Live Retrieval using CQL (Confluence Query Language), here is a simplified breakdown of how that works:
You ask a question (e.g., "How do I configure the payment gateway? Do we have any support articles on Confluence?")
The Confluence Reader Agent in SQAI converts your natural language prompt into a CQL query.
It executes this query against your live Confluence instance.
SQAI downloads and reads only the content of the pages returned by that specific query to formulate an answer.
⚠️ Warning
If the CQL query doesn't find the page or returns nothing, SQAI's Agents can't read or analyze its content.
2. Search Filters
Because of this workflow, your prompt acts as a search filter.
If your prompt is too vague, the generated CQL query might be too broad or miss the specific keywords needed to surface the right document. To ensure success, treat your prompt like a search engine query. Include specific "anchors" that help the Agent narrow down the search:
Keywords: Specific terms found in the Page Title.
Labels: Jira/Confluence labels (e.g.,
'release-notes','Q1-2026','API-Specs').Space Names: The specific Confluence Space where the doc lives (e.g.,
'Engineering','WMS','HR-Policies').Timeframes: When the document was last updated (e.g.,
'last 3 months').
3. Effective Prompting Strategies to Avoid Fuzzy Searches
Here are three scenarios to help you structure prompts that generate high-quality CQL queries.
Scenario A: Searching by Label (Highly Recommended)
Labels are often the most reliable way to group documentation. If you label your release notes, use that in your prompt.
Prompt:
"Find Confluence pages with the label 'release-notes' from the last 3 months and summarize the key changes in the authentication module."
Scenario B: Targeting a Specific Space
If you know the document is in the Engineering folder, tell SQAI to ignore the Marketing folder.
Prompt:
"Search in the 'Engineering' space on Confluence for pages containing 'database migration' in the title and list the prerequisites mentioned."
Scenario C: Broad Keyword Retrieval
If you are unsure of the location, use distinct, unique keywords.
Prompt:
"Retrieve documents from Confluence related to 'onboarding flow' and explain the steps a new user has to go through according to the documentation."
4. Advanced Troubleshooting: Mind Your "Domain Language"
CQL is precise, it searches for exact matches. It does not natively understand that two different terms might mean the same thing in your specific company culture (your "Domain Language").
The Problem:
Your teams use "Production Order," "Manufacturing Order," and "Line Order" interchangeably to refer to the same document type.
The Risk:
If you ask: "Find information on Production Orders," the Agent will generate a query looking for that exact string. It will miss pages titled "Line Order 123" or "Manufacturing Setup."
The Fix:
Use Logic Operators Explicitly tell SQAI to look for synonyms by using "OR" logic in your prompt. This forces the generated CQL to broaden its scope.
Prompt:
"Search in the 'WMS' space for pages containing 'Production Order' OR 'Manufacturing Order' in the title and list the prerequisites."
5. Still Stuck?
If you are still having trouble retrieving specific content:
Check Permissions: Ensure the SQAI integration user has read access to the specific Confluence Space.
Verify the Page Title: Does the page title actually contain the keywords you are using?
Review CQL Syntax: For deeper technical insight into how Confluence indexing works, you can review the Atlassian CQL Guide."