Man Efficient

A Comprehensive Guide to Using Confluence Query Language (CQL)

March 18, 2024
Josh Costella

We’ve all been there before: you know exactly what content you need but finding it in Confluence feels like searching for the mate to a sock in a big pile of laundry. Confluence is a powerful collaboration and knowledge management tool, but sifting through pages of project plans, reports, or meeting notes can be time-consuming. 

The problem is that in today’s digital workspace, there’s no time to waste. Being able to efficiently search for content is crucial for user productivity and effective knowledge management. That’s where Confluence Query Langage (CQL) comes in; it’s key to navigating a sea of content. In this article, we explore what Confluence Query Language is and share best practices that will improve your Confluence search results.

What is Confluence Query Language (CQL)?

Confluence Query Language (CQL) is a valuable tool for enhancing search capabilities, streamlining content retrieval, and optimizing productivity within Confluence. Unlike basic search functions, CQL allows for precise, targeted searches. 

It’s like having a GPS in the vast world of Confluence, guiding you to the exact information you need without the detours. CQL operates similarly to Jira Query Language (JQL), enabling users to construct both basic and complex queries using a combination of keywords, operators, and search parameters.

Benefits of Using CQL

  • Precise Content Retrieval: Whether searching for pages, attachments, comments, or labels, CQL facilitates efficient content retrieval even amidst vast information repositories.

  • Enhanced Search Flexibility: With CQL, users can construct queries tailored to their unique search criteria, utilizing a wide range of operators such as AND, OR, NOT, as well as wildcards and proximity searches (more about this later!). 

  • Improved Workflows and Productivity: By leveraging the advanced search capabilities of CQL, teams can streamline their workflows and save valuable time spent searching for content. Whether tracking down specific documents, locating relevant discussions, or identifying recent updates, CQL makes information retrieval a breeze. 

  • Facilitates Automation and Integration: CQL can be integrated with automation tools and scripts to automate repetitive search tasks, enhancing efficiency and reducing manual overhead. 

Constructing A CQL Query

Complex Text Search with AND/OR Operators:

  • Description: This search combines keywords with logical operators to refine results based on multiple criteria. 

  • Example: text ~ "project plan" AND (text ~ "Q4 results" OR text ~ "2024 forecast")

This query is ideal for finding documents that contain "project plan" and either "Q4 results" or 2024 forecast," making it perfect for comprehensive project reviews.

Combining Space, Type, and Label Functions:

  • Description: Filters content by space, type, and labels for highly advanced searches.

  • Example: space = "Marketing" AND type = "blogpost" AND label IN ("campaign", "Q3")

Use this query to locate all blog posts in the "Marketing" space tagged with "campaign" or "Q3," streamlining content retrieval for marketing analysis.

Advanced Date Range and User Activity Search:

  • Description: Searches for content modified within a specific timeframe by certain users.

  • Example: lastmodified >= "2023-01-01" AND lastmodified <= "2023-03-31" AND modifier IN ("user1", "user2")

This query helps track the recent contributions or modifications made by specific team members in the first quarter of 2023, useful for performance reviews or project audits.

Nested Query for Parent Page and Content Status:

  • Description: Uses nested queries to find pages under a specific parent that are in a particular status. Aimed at organizations needing to ensure all pages under "Project Overview" are up-to-date, this query filters for current status pages, aiding in content management and review processes.

  • Example: ancestor = "Project Overview" AND status = "current"

This query is aimed at organizations needing to ensure all pages under "Project Overview" are up-to-date, this query filters for current status pages, aiding in content management and review processes.

Content Search Across Multiple Spaces with Exclusion Criteria:

  • Description: Finds content across selected spaces, excluding certain labels or statuses.
  • Example: space IN ("HR", "IT") AND label NOT IN ("archived") AND status != "draft"

This sophisticated query is designed for accessing a broad spectrum of active, non-archived content across HR and IT departments, excluding drafts, for cross-departmental initiatives or audits.

Additional CQL Best Practices for Improving Your Search Results

  • Use Wildcards: Expand searches with wildcards (*) for variations of a word, like title ~ "report*" to find "report," "reports," "reporting."

  • Apply Logical Operators: Refine searches with "AND," "OR," "NOT" to narrow, broaden, or exclude results.

  • Group Conditions: Use parentheses ( ) to structure complex queries and control the application of logical operators.

  • Be Specific with Dates: Filter content within precise timeframes, i.e., created >= "2023-01-01" AND created < "2023-07-01".

  • Filter by Space and Type: Narrow down results by specifying the space or content type (page, blog post) at the start.

  • Utilize Labels and Statuses: Employ labels and content statuses to categorize and find relevant content efficiently.

  • Experiment and Refine: Continuously adjust and refine your queries based on results to improve efficiency.

Get Back to The Work That Matters Most

Using CQL means less time hunting for information and more time to focus on the work that matters most. Besides saving you time, CQL is one of many tools within the Atlassian ecosystem that helps foster a collaborative work environment and enhance the employee experience.

The Atlassian platform is designed to keep information flowing freely through the organization, and Praecipio can customize your tools to support your company's unique needs. As one of the fastest-growing Atlassian partners, we’ve seen and solved every problem thrown our way. With experts in every tool–from Confluence to Jira Align–count on our team of experts to help you navigate all things Atlassian. 

Contact us about making your Atlassian journey a successful one. 

Put Your Atlassian Tools to Work

Optimize Your Atlassian Stack with Praecipio