Kaizen #207 - Answering your Questions | Advanced Queries using COQL API

Kaizen #207 - Answering your Questions | Advanced Queries using COQL API



Hi everyone, and welcome to another Kaizen week!

As part of Kaizen #200 milestone, many of you shared topics you would like us to cover, and we have been addressing them one by one over the past few weeks. Today, we are picking up one of those requests - a deep dive into advanced queries using Zoho CRM’s COQL APIs.

When you start building complex applications on top of Zoho CRM, you may feel that basic record fetch APIs like GET records are not enough. Business logic often demands far more, like combining data from multiple modules, applying conditional filters, grouping results, or even running aggregate calculations.

This is exactly where COQL (CRM Object Query Language) shines. If you have already used COQL for straightforward queries, this post will help you go further. 

COQL Recap - Why Use It?

COQL is your go-to when you need more than what the standard GET Records API can provide. It gives you:

  • SQL-like flexibility for querying CRM data.
  • Access to related records across multiple modules using lookups and joins.
  • Powerful filtering, aggregation, and sorting well beyond simple searches.

In short: use COQL when you want fine-grained control over results, complex reporting logic, or performance improvements in large data environments.

Understanding COQL Queries

The Query API (COQL) is best when you need flexible record retrieval without chaining multiple API calls or creating custom views.

Instead of building and maintaining complex filters in the UI, you can describe your data needs in one SQL-like query.

For example, with COQL you can:

  • Fetch all products within a certain price range that also have a 5-star rating, sorted by price.
  • Filter deals based on details from a related module, like the Vendor’s status.
  • Pull a precise slice of data on-demand without altering CRM views.

What kind of queries are supported?

COQL currently supports only the SELECT statement, which lets you pick fields, apply conditions, sort results, and control pagination.

A typical query looks like this:

SELECT {field_api_namesFROM {module_api_nameWHERE {field_api_name} {comparator} {valueGROUP BY {field_api_name} ORDER BY {field_api_nameASC/DESC LIMIT {limitOFFSET {offset}

  • FROM - specifies the module to query
  • WHERE - filters records based on conditions

  • GROUP BY - groups records by one or more fields for aggregation
  • ORDER BY - sorts results ascending or descending
  • LIMIT - restricts the number of records returned
  • OFFSET - skips a certain number of records before fetching results

Example:

{

 "select_query" : "select Last_Name, First_Name, Mobile, Final_Score from Leads where Lead_Status 'Not Contacted' order by Final_Score desc limit 5 offset 10"

}


The above query retrieves five Leads who have not been contacted, ordered by Final_Score, skipping the first 10(OFFSET). You can also use the shorthand LIMIT offset, limit:

{

 "select_query" : "select Last_Name, First_Name, Mobile, Final_Score from Leads where Lead_Status = 'Not Contacted' order by Final_Score desc limit 10, 5"

}


Supported Data Types & Operators

COQL supports multiple field types, each with dedicated operators:

Field Type

Supported Operators

Text, Picklist, Email, Phone, Website, Autonumber 

=, !=, like, not like, in, not in, is null, is not null

Lookup

=, !=, in, not in, is null, is not null

Date, DateTime, Number, Currency

=, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null

Boolean

=

Formula

If the return type is:

  1. Decimal/Currency/Date/Datetime: =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
  2. String: =, !=, like, not like, in, not in, is null, is not null
  3.  Boolean: =


Queries can be further refined with sorting (ORDER BY) and pagination using LIMIT and OFFSET.

Aggregate functions

COQL supports aggregate functions to summarize data:

  • SUM(field) – total of numeric values
  • MAX(field) – largest value
  • MIN(field) – smallest value
  • AVG(field) – average value
  • COUNT(*) – number of records matching criteria 


Please note that aggregate functions are supported only for numeric data types such as number, decimal, currency, etc.

Wildcards

The % character is supported with the LIKE operator for flexible text matching:

  • '%tech' → values ending with “tech”
  • 'C%' → values starting with “C”
  • '%tech%' → values containing “tech”


With these building blocks, you can already express a wide range of queries. Let’s now move into advanced scenarios where COQL really shines.

Beyond basics: COQL Patterns for real-world scenarios

Once you are comfortable with the basics of COQL, you can start combining them into more powerful query patterns. Some of these go beyond simple filtering and field selection, helping you minimize API calls, handle relationships, and emulate unsupported features.

1. Advanced Filtering & Conditions

Beyond equality, COQL supports operators like LIKEINBETWEEN, and date comparisons.

Example: Fetch Leads from the IT or Finance industry created in the year 2025.

{

 "select_query": "select Full_Name, Industry from Leads where Industry in ('IT', 'Finance') and Created_Time between '2025-01-01T00:00:00+05:30' and '2025-12-31T23:59:59+05:30'"

}


Use case: Run targeted campaigns or segment leads for analysis without multiple API calls.

2. Combining Multiple Conditions

You can query diverse conditions, combining exact, partial matches, and set memberships.

Example: Pre-qualified leads in target industries with company names containing “zylker”:

{

 "select_query": "select First_Name, Last_Name from Leads where (((Lead_Status = 'Pre-Qualified') and (Company like '%zylker%')) and Industry in ('Technology', 'Government/Military'))"

}



Use case: Sophisticated audience segmentation or analytics for campaigns.

3. Fetching related records and their fields using Joins (Dot notation)

COQL allows you to retrieve related records efficiently by navigating lookup relationships using dot notation. This makes it possible to pull in contextual information across modules without chaining multiple API calls.

Single-level join: Fetch contacts and their account names, excluding a specific account:

{

 "select_query": "select Last_Name, First_Name, Account_Name.Account_Name, Owner from Contacts where (Account_Name.Account_Name != 'Zylker') limit 2"

}


Sample use case: Retrieve all contacts along with their associated account names while excluding certain accounts (e.g., competitors or internal test accounts). This avoids multiple queries across modules and helps in cleaner campaign targeting.

Hierarchical / nested join: Fetch contacts whose accounts have a parent account named “Kings”:

{

 "select_query": "select Account_Name, Account_Name.Parent_Account.Account_Name from Contacts where Account_Name.Parent_Account.Account_Name = 'Kings' limit 5"

}


Sample use case: Easily retrieve multi-level relationships such as parent-child accounts for reporting, territory alignment, or hierarchical sales analysis.

Multi-Level Join with Extended Lookup : Fetch contacts, their accounts, the parent accounts of those accounts, and the owner of the parent account:

{

 "select_query": "select Last_Name, First_Name, Account_Name.Account_Name, Account_Name.Parent_Account, Account_Name.Parent_Account.Owner AS 'Parent Account Owner', Owner from Contacts where (Account_Name.Account_Name != 'Zylker') limit 2"

}


Sample use case: Useful in complex account management and escalation scenarios where responsibility spans multiple levels. For instance, sales managers may want to see not just the contact and their account, but also which parent account owner is responsible for the overall relationship. These types of queries are helpful in large enterprises with layered ownership structures.

4. Using Subqueries to detect missing relationships

COQL supports subqueries to filter based on related module data or detect missing relationships.

Example: Find contacts whose accounts have no closed deals:

{

 "select_query": "select Full_Name, Email from Contacts where Account_Name not in (select Account_Name from Deals where Stage = 'Closed Won')"

}


Use case: Identify potential follow-ups, audit compliance, or uncover opportunities.

These types of queries are handy for:

  • Sales follow-ups – identify contacts from accounts that haven’t yet converted.
  • Compliance checks – ensure certain accounts meet deal requirements.
  • Pipeline building – target untouched accounts for new opportunities.

By combining subqueries with conditions like NOT IN, COQL makes it easy to surface hidden opportunities that would otherwise require multiple API calls and custom logic.

NoteSubqueries in COQL can return a maximum of 100 records. If the inner query has more than 100 matches, any extra records are ignored. This means you may get incomplete results in larger datasets. In such cases, it is better to redesign the query using joins or multiple API calls, which can handle broader datasets without this limit.

Advanced COQL Querying: Real-World Patterns

Once you’ve mastered filters, joins, and subqueries, you can combine them for advanced business logic. 

1. Filtering Deals Based on Account Attributes

Generic Use Case:
You want to prioritize deals connected to high-value accounts that meet specific business criteria, such as strong credit ratings or key industries.

Retrieve all deals for accounts that:

  • Have a high credit rating (>750)
  • Belong to a specific industry, e.g., Communications

COQL Query:

{

 "select_query": "SELECT Deal_Name, Amount, Account_Name, Contact_Name.Email FROM Deals WHERE Account_Name in (SELECT id FROM Accounts WHERE Credit_Rating > 750 AND Industry = 'Communications') AND Stage != 'Closed Won'"

}


Dynamically filter deals by account attributes while fetching related contact details in a single query.

2. Emulating MIN/MAX for Date fields

When working with date fields in COQL, a common analytical need is to compare records against the latest date from a related subset. For example, identifying deals that closed before the most recent high-value deal.

Intuitively, one might try to use aggregate functions like MAX() on a date field in a subquery, such as:

{

 "select_query": "SELECT Deal_Name FROM Deals WHERE Closing_Date < (SELECT MAX(Closing_Date) FROM Deals WHERE Amount > 500000)"

}

Warning
However, COQL currently does not support aggregate functions like MAX() or MIN() on Date or DateTime fields. Attempting this will result in errors or unexpected behavior, as COQL aggregates are primarily designed for numeric fields.

Workaround: Using Subquery with ORDER BY and LIMIT

Instead of MAX(), the recommended COQL approach leverages sorting and limiting the result set to a single latest date within a subquery:

{

 "select_query": "select Deal_Name from Deals where Closing_Date < (select Closing_Date from Deals where Amount > 500000 order by Closing_Date desc limit 1)"

}


How this works:

The inner subquery fetches the single most recent Closing_Date where deals exceed $500,000, ordering by date descending and limiting to one record. The outer query then retrieves all deals closed before that date.

This pattern mimics the MAX() date comparison in a manner supported by COQL’s current capabilities. You can apply the same approach with ascending sort order to emulate MIN() as well.

3. Combining Multiple Subqueries for Complex Business Logic

Real-world CRM scenarios often require filtering records based on multiple interconnected conditions across different modules. Consider this sales intelligence use case: you want to identify Contacts who are:

  • Associated with Accounts that have annual revenue greater than $1000000000000
  • Connected to Deals that were created in the previous quarter    

{

 "select_query": "SELECT First_Name, Last_Name, Email, Account_Name.Account_Name FROM Contacts WHERE Account_Name in (SELECT Account_Name FROM Deals WHERE Created_Time >= '2025-06-01' AND Account_Name in (SELECT id FROM Accounts WHERE Annual_Revenue > 1000000000000)) "

}


Query Breakdown:

  • Innermost subquery: (SELECT id FROM Accounts WHERE Annual_Revenue > 1000000000000) identifies high-revenue accounts
  • Middle subquery: (SELECT Account_Name FROM Deals WHERE Created_Time >= '2022-07-02T15:18:31+05:30' AND Account_Name in (...)) filters for accounts with deals created after the specified date that are also high-revenue accounts
  • Main query: Retrieves contact details for all contacts associated with these filtered accounts while fetching the related account names via JOIN


This pattern finds contacts from high-value accounts that have had recent deal activity, combining temporal filtering with revenue-based account qualification in a single efficient query.

Dynamic Account and Deal Performance Analysis

Imagine you need to find all Leads from industries where accounts have historically closed high-value deals (over $100K) and those leads have "Hot" ratings.

This requires filtering leads based on:

  • Industry performance from accounts with successful deals
  • Lead rating criteria
  • Retrieving lead details with industry information


{

 "select_query": "SELECT First_Name, Last_Name, Lead_Source, Company, Industry FROM Leads WHERE Industry in (SELECT Industry FROM Accounts WHERE id in (SELECT Account_Name FROM Deals WHERE Amount > 100000 AND Stage = 'Closed Won') GROUP BY Industry) AND Rating = 'Hot'"

}


What makes this powerful:

  • Inner subquery (SELECT Account_Name FROM Deals WHERE Amount > 100000 AND Stage = 'Closed Won') identifies accounts with successful high-value deals
  • Outer subquery (SELECT Industry FROM Accounts WHERE id in (...) GROUP BY Industry) gets the industries of those successful accounts
  • Groups by Industry to get unique industry values and avoid duplicates
  • Main query finds leads in those proven successful industries with "Hot" ratings.

    Note: Both subqueries in this query are limited to 100 records each. If either the Deals or Accounts module returns more than 100 matches, the additional records are silently ignored. This can lead to incomplete results when working with larger datasets. For scenarios where the inner queries are expected to return more than 100 records, redesign the query using joins or break it down into multiple API calls for complete coverage.


Conclusion

By going beyond simple record fetches, COQL gives you the power to do true analytics and querying. By mastering patterns that range from straightforward joins to complex multi-module subqueries, you can consolidate multiple API calls into a single query, reduce complexity, and streamline performance. At the same time, dynamic filtering across modules facilitates richer business logic, while relationship-aware queries let you build automations that can handle real-world exceptions with precision.

As you implement these patterns, remember that the most powerful COQL queries often combine multiple techniques: JOINs for data enrichment, subqueries for dynamic filtering, and careful aggregation for performance optimization. However, it is equally important to understand COQL's limitations too. Being aware of these limitations will help you design effective workarounds and choose the right approach for your specific use cases. For a comprehensive list of limitations, please refer to our COQL Limitations documentation.

Start with simpler patterns and gradually build complexity as your use cases demand. The investment in mastering COQL will pay you with cleaner code base, better performance, lesser credit consumption, and more sophisticated CRM functionality.

We hope that you found this post on COQL useful. If you have any queries or need further assistance, please feel free to comment below or email us at support@zohocrm.com. We are here to help!



    • Recent Topics

    • Google Fonts Integration in Pagesense Popup Editor

      Hello Zoho Pagesense Team, We hope you're doing well. We’d like to submit a feature request to enhance Zoho Pagesense’s popup editor with Google Fonts support. Current Limitation: Currently, Pagesense offers a limited set of default fonts. Google Fonts
    • Control Position of “X” (Close) Button in Popup Editor

      Hello Zoho PageSense Team, We hope you're doing well. We would like to request a customization improvement in the PageSense popup editor. Current Limitation: Currently, the position of the “X” (close) button is fixed and cannot be customized in the popup
    • Add Standalone “Save” Button in Pagesense Popup Editor

      Hello Zoho Pagesense Team, We hope you're doing well. We would like to request an important usability improvement in the Pagesense popup editor. Current Limitation: There is currently no dedicated Save button while building a popup. The only way to save
    • Text Direction Control in Pagesense Popup Editor

      Hello Zoho Pagesense Team, We hope you're doing well. We’d like to submit a feature request to add text direction control in the Pagesense popup editor. Current Limitation: Currently, the popup editor does not provide native support for RTL (Right-to-Left)
    • Autosave in Pagesense Popup Editor

      Hello Zoho Pagesense Team, We hope you're doing well. We’d like to submit a feature request to enhance the Pagesense editor with an autosave functionality. Current Limitation: Currently, changes made in the Pagesense editor must be manually saved. In
    • Billing frequency is not displayed correctly.

      Hello There is an issue while displaying the billing frequency on a subscription quote. I am able to activate the subscription details and get this lovely overview: If I am adding a Plan which I charge quarterly, first of all it should be possible to
    • Creating Secret via Vault API

      Hi I am trying to create a secret through vault api.  This is the response I get. One thing I am not sure is how to decrypt the secretdata, how to get the secrettypeid? {     "operation": {         "result": {             "error_code": "",             "message": "Sorry, we are unable to process your request.",
    • Is It Possible to Hide Menu Option from Main Navigation?

      Is it possible to hide a menu option, e.g. Admin, from the Main Navigation based on some criteria, e.g. login = zoho.adminuser
    • Unleash the power of detail, with Table View.

      What use is context that's not available where you need it? With this in mind, we bring you the Table View. This feature will add more power to the way you organize and work through your ticket load. Table View comes in handy when you want more control over the ticket information you see. This is a nifty tool for users who find themselves limited in terms of the level of information that is being offered in the Classic View and Compact View. With an upper limit of 15 columns, agents can glean most
    • Kaizen #126 - Circuits in Zoho CRM - Part 1

      Hello everyone! Welcome back to another week of Kaizen! Today, we will discuss an exciting topic—Circuits in Zoho CRM. For starters, we will discuss what Circuits are, how beneficial they are for businesses, different views of a Circuit, and the different
    • 'Statement of Accounts does not exist' error received, when creating PO using api in Zoho Inventory

      Here is request json -- JSONString = { "date": "2019-09-24", "purchaseorder_number": "PO-6-1", "delivery_date": null, "delivery_org_address_id": 36221200000056XXX, "vendor_id": 362212000000564XXX, "attention": "Testing", "line_items": [{ "unit": "Pieces", "account_id": 36221200000003XXX, "quantity": 1, "item_id": 362212000000049XXX, "tax_type": "", "tax_name": "", "name": "One HD", "purchase_rate": 85, "tax_percentage": 0, "item_total": 85.00, "tax_id": "", "warehouse_id": 362212000000564XXX }] }
    • Multiple clients in one project

      Hi team, What is the possibility to have more than one client to be linked for one project in the Zoho Books? Our business model is to have a project, and this project have expenses/bills, as well, we issue invoices for this same project to several customers.
    • I can receive but not send emails

      Hello, I've been not able to send emails for almost a year now. I been using alternate email to do this. I want to know how to fix this so I can use my zoho account normally again.
    • Support Bots and Automations in External Channels

      Hello Zoho Cliq Team, How are you? We actively use Zoho Cliq for collaboration, including with our external developers. For this purpose, external channels are a key tool since they work seamlessly within the same interface as all of our other channels
    • Workdrive on Android - Gallery Photo Backups

      Hello, Is there any way of backing up the photos on my android phone directly to a specific folder on Workdrive? Assuming i have the workdrive app installed on the phone in question. Emma
    • Can receive but not send messages in Zoho Mail

      Hello! I was able to configure my email client successfully in that I can receive messages just fine. However, when I send messages out, they seem to go out fine (I don't receive any errors or anything), but the recipient does NOT receive those messages.
    • Clients not receiving emails

      I've been informed that my emails are not being received. Is there anything that I should look into to rectify this? Many thanks!
    • Rendering PDF to view on page

      My company upload lots of PDF files onto Zoho. But every time we open it, it downloads the file instead of viewing it on the web page. Does Zoho allow uploaded PDF files to be rendered to view on web page yet? I've been trying to use <embed> or <object> but it cannot be loaded.  (similar thread: https://help.zoho.com/portal/community/topic/how-to-open-a-pdf-file-of-a-view-in-preview-mode)
    • Dynamically Fetching Lookup Field Display Value

      I have an audit trail form, Audit_Changes, that tracks old vs new values across different forms. For lookup fields, the old/new value is the ID, but I also need the display value. What's a best practice for dynamically fetching the display value of the
    • Zoho Toolkit Email Signature Generator

      I'm having real issues with the email signature generator with no matter where I host the photo, Zoho doesn't seem to show the photo on the link provided?
    • Ability to Create New Items When Zoho Trident is Minimized via tray or taskbar icon

      Allow users to create new items (emails, calendar events, tasks, etc.) directly from the system tray icon or by right clicking the task bar icon, even when the window is minimized or not actively running in the foreground. This enables quick access to
    • I can not see Undeliverable emails from my Mass Email Leads activity in CRM

      I am sending email templates and I can not see the Undeliverables? I only receive the "Out of Office" replies and any manual replies from the lead. Can you please let me know where the Undeliverable emails are sent so I can use the information to clean up the database?
    • Select Zoho Contacts as Meeting Participants in Zoho Cliq

      Hello Zoho Cliq Team, We hope you're doing well. We would like to request an enhancement to the meeting scheduling functionality in Zoho Cliq. Current Limitation: When scheduling a meeting in Zoho Cliq, participants can only be selected from: Organization
    • Ability to Select External Users from Participants List When Scheduling Meetings

      Hello Zoho Cliq Team, We hope you're doing well. We would like to request an enhancement to the meeting scheduling experience in Zoho Cliq. Current Limitation when scheduling a meeting in Zoho Cliq: External users can be selected from the list only under
    • Kaizen #212 - Map Dependency Fields in Zoho CRM using APIs

      Hi Everyone!! Welcome back to another week of Kaizen series! Over the past few weeks, we have been addressing your questions and feedback shared through our Kaizen 200th feedback form. Thank you for your continued engagement and thoughtful queries. We
    • Outdated state in mexico

      Hello Zoho team, the drop down to add the state for customers, when they introduce their state in mexico has a city named “Distrito Federal” that name changed many years ago to “ciudad de mexico”. could you please update this so my clients can find the
    • Is anyone using Zoho Flow with airtable?

      I need to build a flow that collects data from airtable and uses some of that data to create folders and files in google drive. I have fully function version of this in zapier and want to migrate to zoho. I am trying to perform a very basic fetch from
    • AI in Zoho Workplace: A Sneak Peek into What’s Coming!

      Hello everyone, We’re super excited to share something we’ve been working on and we want you to be part of it! You may have seen our announcement blog post introducing a major evolution in how AI works within Zoho Workplace. Want to be among the first
    • Meet Canvas' Grid component: Your easiest way to build responsive record templates

      Visual design can be exciting—until you're knee-deep in the details. Whether it's aligning text boxes to prevent overlaps, fixing negative space, or simply making sure the right data stands out, just ironing out inconsistencies takes a lot of moving parts.
    • Best way to share/download presentation files in Zoho without losing formatting?

      Hello Zoho Community, I often work with PPT/PDF files in Zoho Docs and share them with colleagues. While PDFs usually give a direct download option, I’ve noticed that PPT/PPTX files sometimes only open in the viewer without a clear download link. Is there
    • Workflow Failure - Notifications

      Good afternoon, I have just experienced an error whereby a Workflow failed, for a reason currently unknown. The problem is that one of my users had to flag this manually (thankfully he's very thorough) and this otherwise would have flown under the radar.
    • Introducing Bin Locations In Zoho Inventory

      Hello users, We are excited to let you know that your wait for the Bin Locations feature has now come to an end! Yes, you heard us right! We are here to introduce the much-awaited Bin Locations now in Zoho Inventory. But before we dive into the feature
    • Error "Invalid client task found corresponding properties" only when triggered from workflow ?

      Hi All, I am facing an error message I never encountered previously: Error in executing On Add - On Load script Error in executing thisapp.get_all_projects_api_call function. Line:(2) Error in executing thisapp.getAccessTokenFromRefreshToken function.
    • How to interpret Campaign report statistics - definitions/explanation

      I am trying to make sure I understand the Campaign report correctly Do you have a list of definitions for: Delivered - it has reached the recipient's inbox Campaign reach - is this the number that have opened the campaign email? Unique Opens Clicks/Open
    • Feature request - pin or flag note

      Hi, It would be great if you could either pin or flag one or more notes so that they remain visible when there are a bunch of notes and some get hidden in the list. Sometimes you are looking for a particular name that gets lost in a bunch of less important
    • Schedule a Call by Date and Time when a specific lead status is selected

      Hi Wanting to create a workflow where a call can be scheduled by date & time when a specific lead status is selected. Can only currently set the date by Due Date - Trigger Date - Plus 'x' day(s) Thanks
    • Zoho CRM's Copy Customization functionality now works across DCs, for customized accounts, and more

      Availability This feature is available in Standard, Professional, Enterprise, and Ultimate editions. These changes have been rolled out to all users in all DCs. For more information, please refer to these help documents: Overview | Instructions Hello
    • How can I bold text on Zoho Forms submit buttons?

      In the old theme builder, I could bold the text on a form's submit button. With the new theme builder, I can only change the text of the header or fields in the form, and not the button itself.
    • Hiding Pre-defined Views

      You can enhance Zoho with custom views - but you cannot hide the pre-defined views. Most users focus on 4 or 5 views. Right now for EVERY user EVERY time they want to move to one of their 4 or 5 views - they have to scroll down past a long list of pre-defined views - we don't use ANY of the pre-defined views. Adding the feature to allow a predefined view to be hidden completely or only visible to certain users would be a big improvement in usability for Zoho CRM. This feature is already available
    • Rich-text fields in Zoho CRM

      Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile
    • Next Page