Kaizen 81 - COQL API - Part II

Kaizen 81 - COQL API - Part II

Hello everyone! 
Welcome to another week of Kaizen! 
In continuation to last week's post on COQL API, we will discuss the rest of the field types and their supported operators with detailed examples in this post. 

Supported field types and Operators

Please refer to the COQL API - Part I Kaizen post for the first three field types and their supported operators.

4) Boolean

The supported operator for Boolean field is =. You should provide the value as either true or false.

Sample Query

{
 "select_query" : "select Product_Name, Product_Code from Products where Product_Active = 'false' limit 2"
}

This sample query selects the Product_Name and Product_Code fields from the Products module where Product_Active is false, and limits the result to only 2 records.
Sample Response:
{
    "data": [
        {
            "Product_Code": "SR-001",
            "Product_Name": "Sigma",
            "id": "4876876000001036109"
        },
        {
            "Product_Code": "SR-003",
            "Product_Name": "Alpha",
            "id": "4876876000001039006"
        }
    ],
    "info": {
        "count": 2,
        "more_records": false
    }
}

what_Id support in COQL

=, !=, in, not in, is null, is not null are the supported operators. what_Id support is extended only to Tasks, Calls and Events. The what_Id field could be a lead or a contact.

Sample Query

{
    "select_query": "select 'What_Id->Leads.Last_Name' from Tasks where (('What_Id->Leads.id' in ('4876876000000900134','4876678000000900987')) AND ('What_Id->Leads.Industry' != 'ERP'))"
}

This sample query queries for the last name of leads associated with tasks where the lead ID is either '4876876000000900134' or '4876678000000900987', and the lead's industry is not 'ERP'.
Sample Response:
{
    "data": [
        {
            "What_Id->Leads.Last_Name": "Perry",
            "id": "4876876000001103044"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Roles and Profiles support in COQL

COQL supports roles and profiles lookup fields, allowing users to retrieve the owner's profile details such as ID, name etc, and the owner's role details using COQL queries. The supported comparators are =, !=, in, not in, is null, is not null.

Sample Query

{
    "select_query": "select Owner.role.id,Owner.role.name,Owner.role.reporting_to, Owner.role.share_data_with_peers, Owner.role.description, Owner.profile.id from Leads where Last_Name is not null LIMIT 1"
}

This query fetches the Profile details and Role details of the owner of one record from the Leads module. 

Sample Response:
{
    "data": [
        {
            "Owner.role.reporting_to": null,
            "Owner.profile.id": "4876876000000026011",
            "Owner.role.name": "CEO",
            "Owner.role.description": "crm.security.role.admin.desc",
            "Owner.role.share_data_with_peers": true,
            "Owner.role.id": "4876876000000026005",
            "id": "4876876000000333403"
        }
    ],
    "info": {
        "count": 1,
        "more_records": true
    }
}

Alias support

Supported operators : =, !=, in, not in, is null, is not null
Alias support in COQL allows users to simplify complex SELECT field names by giving them custom names or aliases. Using aliases in the SELECT column and ORDER BY class can make column names easier to understand and remember. For instance,  What_Id->Leads.Last_Name from our previous example can be given an alias in the SELECT query as follows.

Sample Query

{
    "select_query": "select 'What_Id->Leads.Last_Name' AS 'Lead Name' from Tasks where (('What_Id->Leads.id' in ('4876876000000900134','4876678000000900987')) AND ('What_Id->Leads.Industry' != 'ERP'))"
}

Sample Response:
{
    "data": [
        {
            "id": "4876876000001103044",
            "Lead Name": "Perry"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

If you compare this response with the sample response in the what_Id section above, you can see that the key 'What_Id->Leads.Last_Name'  is replaced with the Alias 'Lead Name'  in here. 

Aggregate Function Support in COQL

Aggregate functions in COQL allow you to perform calculations on groups of records in a module. The available aggregate functions include SUM, MIN, MAX, AVG, and COUNT.

1. SUM

Use this function to sum up the values of an aggregate field in a module. 

Sample Query 1

{
    "select_query":"select SUM(Grand_Total) from Quotes WHERE Quote_Stage = 'Draft' "
}

This Query uses the SUM function to calculate the total value of the Grand_Total field for all quotes in the Draft stage in the Quotes module.
Sample Response:
{
    "data": [
        {
            "SUM(Grand_Total)": 1073660
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Sample Query 2

{
    "select_query": "select SUM(Grand_Total), Account_Name.Account_Name AS 'Account Name', Billing_Country from Invoices where ((Status != 'Paid') and ((Billing_Country ='USA') OR (Billing_Country = 'Canada'))) GROUP BY Account_Name.Account_Name, Billing_Country ORDER BY 'Account Name' ASC"
}

This query retrieves the total SUM of the Grand_Total field, along with the Account_Name and Billing_Country from the Invoices module for those records whose Status field is not equal to 'Paid' and the Billing_Country field is either 'USA' or 'Canada'. The results are grouped by the Account_Name and Billing_Country fields and ordered in ascending order based on the 'Account Name' field.

Note that the 'Account Name' field is specified using the AS keyword to provide an alias for the Account_Name.Account_Name field. We have used the alias for the ORDER BY clause.
Sample Response:
{
    "data": [
        {
            "Account Name": "SR Systems",
            "Billing_Country": "USA",
            "SUM(Grand_Total)": 2430000
        },
        {
            "Account Name": "SR Systems",
            "Billing_Country": "Canada",
            "SUM(Grand_Total)": 60000
        },
        {
            "Account Name": "Zylker systems",
            "Billing_Country": "Canada",
            "SUM(Grand_Total)": 378000
        }
    ],
    "info": {
        "count": 3,
        "more_records": false
    }
}

The response JSON contains the SUM of the Grand_Total fields, Account Name and Billing_Country for each unique combination of Account Name and Billing Country fields that satisfies the filter criteria specified in the query. 

2. MAX

Use this aggregate function to find the largest value of a field in a module. 

Sample Query

{
    "select_query": "select MAX(Amount) AS 'Maximum Deal Amount', Account_Name.Account_Name from Deals where ((Stage = 'Closed Won') AND  (Type = 'Existing Business')) Group by Account_Name.Account_Name"
}

This Query selects the maximum Deal Amount for each account from the Deals module where the stage is Closed Won and the type is Existing Business.
Sample Response:
{
    "data": [
        {
            "Maximum Deal Amount": 6750000,
            "Account_Name.Account_Name": "Benton"
        },
        {
            "Maximum Deal Amount": null,
            "Account_Name.Account_Name": "King"
        },
        {
            "Maximum Deal Amount": 945000,
            "Account_Name.Account_Name": "Morlong Associates"
        }
    ],
    "info": {
        "count": 3,
        "more_records": false
    }
}

3. MIN

Use this aggregate function to find the smallest value of a field in a module. For example, you can use this function to find the Lowest Annual Revenue in the Leads module.

Sample Query: 1:

{
        "select_query": "select MIN(Annual_Revenue) from Leads where Annual_Revenue is not null"
}

Sample Response:
{
    "data": [
        {
            "MIN(Annual_Revenue)": 348.3
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

4. AVG

Use this aggregate function to find the average value of a field in a module. 

Sample Query

{
    "select_query": "SELECT AVG(Amount) AS 'Average Deal Amount' FROM Deals WHERE Type = 'New Business'"
}

This query calculates the average deal amount for all new business deals in the "Deals" module. 
Sample Response:
{
    "data": [
        {
            "Average Deal Amount": 877366.8359999999
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

5. COUNT

Use this aggregate function to count the number of records in a module satisfying a certain criteria. You can use this aggregate function only for number, lookup, and picklist fields.

Sample Query:

{
    "select_query": "SELECT COUNT(Product_Category) FROM Products WHERE Product_Active = 'false'"
}
This sample query queries for the total number of inactive products in the Product module. Please be aware that if there are any products with no value for the product category field, they will not be included in the count.

Important points to remember

  • COQL keywords are not case-sensitive.
  • To prevent ambiguity, the criteria listed in the WHERE clause must be properly enclosed in brackets. If WHERE has more than two criteria such as A, B, and C, use them as either of the following:
    • (A and (B and C))
    • ((A and B) and C)
    • A and (B and C)
    • (A and B) and C.
  • COQL supports only SELECT queries with WHERE, FROM, ORDER BY, LIMIT, and OFFSET clauses and aggregate functions SUM(), MAX(), MIN(), AVG(), and COUNT().
  • The default sort order is ascending based on record ID if ORDER BY is not specified.
  • Use the following format for :
    • Date : YYYY-MM-DD
    • DateTime : YYYY-MM-DDTHH:mm:ss+/-HH:mm
  • The default value for LIMIT is 200 and OFFSET is 0.
  • A maximum of 10,000 records can be fetched using the API.
  • Multi-line fields cannot be used in criteria.
  • COQL doesn't support consent_lookup, subform, profileimage, multiselectlookup, fileupload datatypes.
  • A maximum of 25 criteria can be included in the WHERE clause.
  • A maximum of 50 field API names can be used in the SELECT column of the query.

     Data Type
     Supported Operators
     text
     =, !=, like, not like, in, not in, is null, is not null
     picklist
     =, !=, like, not like, in, not in, is null, is not null
     ownerlookup
     =, !=, in, not in, is null, is not null
     lookup
     =, !=, in, not in, is null, is not null
     date
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     datetime
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     currency
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     boolean
     =
     email
     =, !=, like, not like, in, not in, is null, is not null
     phone
     =, !=, like, not like, in, not in, is null, is not null
     website
     =, !=, like, not like, in, not in, is null, is not null
     double
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     bigint
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     integer
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     formula
     If the return type is:
          Decimal/Currency/Date/Datetime : =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
          String : =, !=, like, not like, in, not in, is null, is not null
          Boolean : =
     autonumber
     =, !=, like, not like, in, not in, is null, is not null
We hope you found this post useful. We will meet you next week with another interesting topic.

If you have any questions or feedback, please let us know in the comments below, or write to us at support@zohocrm.com. We would love to hear from you! 


Additional Reading:








    • Recent Topics

    • Clear String field based on the value of other field

      Hello everyone, We would like to be able to clear a string field (delete whatever has been written and make it empty) when another field (picklist) is changed to a specific value. While I can empty other types of fields, I noticed that I can't do this

    • Custom Deal Name in Lead Conversion Mapping

      I know there are ways to change the name of a Deal after conversion using a custom function, so no need to repost that information. I would like to see the CRM Improved with Deal Name Customisation and I think the Lead Conversion Mapping page would be

    • Within the Basic KPI component in Analytics, it is impossible to set "next" day range as a filter

      Hi there, I am currently setting up a deal dashboard for the Sales team. While it is possible to filter deal records to show records that were created LAST X days only, it looks like a NEXT X days Closing date filter is not available. Would it be possible

    • Invoice status on write-off is "Paid" - how do I change this to "Written off"

      HI guys, I want to write off a couple of outstanding invoices, but when I do this, the status of the invoices shows as "Paid". Clearly this is not the case and I need to be able to see that they are written off in the customer's history. Is there a way

    • For each loop with available time slots

      I am very new to Deluge, and this question was unable to be answered by Zoho Creator tech support upon request. Task at hand: I have a Form with 4 fields: - Date Start - Date End - Dropdown: Time Start: contains time slots (12:00PM, 12:15PM, etc) - Dropdown:

    • Can we have Backorder Management ?

      Can we have Backorder Management ?

    • Converting Amazon Sales Order to Invoice

      Hi there, We need  advice on the Amazon integration with Zoho Inventory. Now, we want to convert all the Sales orders synced from Amazon to Invoices. We want also to include and record the Amazon fees associated with the sales (Amazon fees, FBA fees, Cost of Advertising etc.) However, Sales order only captures the sales proceeds (Gross Sales) in Zoho Inventory. Does anyone currently work with Amazon and can suggest how to correctly process the sales and Amazon payments through Zoho Inventory and

    • Zoho Inventory | Can't uncheck/turn off Advance Tracking

      Hi, I wanted to know if there's a way to turn off Advanced Tracking (such as Serial Number or Batch Tracking) for an item in Zoho Inventory. I’ve read that you might need to delete associated transactions and clear the opening stock to disable these features.

    • Landed Cost application to Vendor Bills from dropship Purchase Orders

      When trying to apply a Landed Cost to a Vendor Bill generated from a dropship Purchase Order, the Landed Cost pop-up window generates a message that "Landed Cost cannot be applied to Bills from dropship Purchase Orders" when trying to save the landed

    • 2 serial numbers for 1 item (Mac address and Serial number)

      There is a way to track 2 serial number type for 1 Item. Ex: Some electronic devices have a MAC address and a serial number. I need to track those 2 numbers

    • Zoho Projects Roadshow, USA - 2024

      Dear Users, We are happy to announce the Zoho Projects Roadshows 2024 in USA. This is an excellent opportunity to learn more about Zoho Projects and gain in-depth knowledge of the advanced features. Our team will also discuss industry specific solutions

    • [Zoho Writer Webinar] Tips on collaboration control in Writer

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of October 2023: Tips on collaboration control in Writer. This webinar will help you understand the various features available in Writer to control collaboration. We'll

    • [Zoho Writer Webinar] Working with tables in Zoho Writer

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of September 2023: Working with tables. This webinar will help you understand the various ways you can use tables to meet your specific needs. The webinar will take

    • [Zoho Writer Webinar] Customize Writer to suit your business process

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of August 2023: Customize Writer to suit your business process. This webinar will cover the various ways to customize Writer to streamline business processes and improve

    • Is there a way to print the dashboard?

      I would like the capability of printing the dashboard - is that possible?

    • Workflows for Timesheet

      Good day, Any way to have timesheet as triggers? I looked into Zoho Flow and into Zoho Project automation but no where can I have timesheet as a trigger. Basically, I would like to trigger something upon timesheet approval. Right now, the only way to

    • Linkedin - Recruiter System Connect

      Hi there! Does anyone here know how to connect Zoho Recruit to Linkedin Recruiter via Recruiter System Connect?

    • [Webinar] A recap of Zoho Writer in 2024

      Hi Zoho Writer users, We're excited to announce Zoho Writer's webinar for December 2024: A recap of Zoho Writer in 2024. This webinar will provide a recap of the features, enhancements, and integrations released in 2024 to enhance your productivity. There

    • Learn how to automate IT asset and incident management with Zoho Writer

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for November 2024: Learn how to use Zoho Writer's fillable forms for IT asset and incident management. This webinar will focus on how Zoho Writer can help you automate your organization's

    • [Webinar] Learn how Zoho Writer can streamline your finance and admin operations

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for October 2024: Streamlining finance and admin operations with Zoho Writer. This webinar will focus on how Zoho Writer can help you generate payslips and automate claim processes.

    • [Zoho Writer Webinar] Learn how Zoho Writer can enhance the productivity of sales teams

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for August 2024: Streamlining sales operations with Zoho Writer. This webinar will focus on how Zoho Writer can help you create sales documents and automate sales routines. There

    • [Zoho Writer Webinar] Learn how to simplify your HR operations: Part 2

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for July 2024: Learn how Zoho Writer can simplify your HR operations: Part 2. This webinar will focus on how Zoho Writer can help HR teams streamline and automate their entire hiring

    • [Zoho Writer Webinar] Learn how to simplify your day-to-day HR operations

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for June 2024: Learn how Zoho Writer can simplify your day-to-day HR operations. This webinar will focus on how to automate your entire hiring process and generate various types of

    • [Zoho Writer Webinar] Use formulas and conditions in Zoho Writer's document automation

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for May 2024: Learn how to use formulas and conditions in Zoho Writer. This webinar will focus on how to use formulas and conditions when automating document generation in Zoho Writer.

    • [Zoho Writer Webinar] Personalize Zoho Writer to suit your needs

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for April 2024: Learn how to personalize Zoho Writer to suit your needs. This webinar will focus on how to easily customize Writer's features at the user and organization level for

    • How to refresh/update module fields in

      Hi, I created a Workspace for CRM years ago. Since that time I've updated the layouts in several modules in CRM but Zoho Analytics displays the previous state fields only. How to refresh the module fields to reflect the actual state in Analytics? BR

    • Data update/pull from a specific field or module

      Hi Team, Currently, if I need a data from a newly added field on a product like Zoho CRM, I need to refresh the whole module to get the new field. This is taking much time for the data to be visible. If the data pull/refresh can be granularized to fetch

    • Lookup field in User module cannot look up to custom modules!

      Hi there, Expense has been great so far but it's sad to see that a simple thing such as allowing a lookup to custom modules from the Users module is not yet implemented. Hope to see this in the next release. Do you have any plan for that?

    • Trigger Zoho Cliq Channel Workflows for API Messages

      Dear Zoho Cliq Team, I hope this message finds you well. We have noticed that reminders or messages posted to Zoho Cliq channels via the API do not trigger channel-based workflows. This limitation means that any bot configured with a participation handler

    • Webhook Trigger for New Messages in Cliq Channels

      Hello, I would like to request a feature to enable webhook triggers when a new message is added to a Cliq channel. This functionality would allow us to seamlessly send important information from Cliq to other relevant systems. This webhook trigger can

    • Ability to Edit the "Current Job Title" dropdown field

      Current experience/Issue: When a user (candidate) uploads resume to Zoho Recruit candidate portal, some fields are prefilled with the info from the resume/cv correctly. However, we've observed that; 1. the "Current Job Title" dropdown field is usually

    • I'm getting an "Invalid_scope" error, even though I used an access token generated with the correct scope.

      I'm getting an "Invalid_scope" error, even though I used an access token generated with the correct scope. Here’s what I did in Postman: Generated the code to create an access token using the following URL: https://accounts.zoho.eu/oauth/v2/auth?scope=ZohoCampaigns.contact.UPDATE&client_id=<client_id>&response_type=code&access_type=offline&redirect_uri=https://1882-2-26-193-161.ngrok-free.app

    • Problem configuring/customizing sales pipeline steps

      Hello, I have created several sales pipelines with different stages in them. Unfortunately I forgot to properly configure these steps (conversion probability, forecast category). How can I modify and customize all these steps? Thnak you by advance M

    • workflow for bounced email gets triggered, but email is status = opened

      Hello, I have a workflow that sends me an email if outgoing email are bounced. Now I got some kind of this emails, but the corrosponding contacts have status = open at the email. Why this bounce-workflow is triggered? Reports > Email Reports > Bounce

    • Power of Automation :: Automatically start / pause / stop timer on task status update.

      Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-

    • Website Access Blocked (from one pc only) when attempting unattended access to any device

      Hello From one of my laptops I cannot access any remote device using unattended access. A Zoho Assist error page didplays 'Website Access Blocked. See attached.

    • Zoho Analytics to Zoho Sheets - automatic update?

      Hi all, If I create a zoho sheet from an Analytics Report or Analytics Data, is there a way for the zoho sheet to automatically update as the Report / Data in analytics updates?

    • Fixed Assets Register

      Thank you Zoho Books for adding fixed assets register. BUT there are certian tweeks that needs to be implemented. I found the following issues and seek improvements. 1) Fixed Asset Register Report in the Report Section has columns which are so much confusing.

    • Link to Desk tickets

      Hello, We are using Analytics to analyze data in Desk. Is there a way to embed a link to a ticket in reports? We'd love to be able to see the drill down data, and click a value in a result row that would launch the Desk Ticket in another window/tab. Thanks

    • Announcing new features in Trident for macOS (v.1.11.0)

      Hello everyone! Trident for macOS (v.1.11.0) is here with interesting features and enhancements to elevate your workplace communication and productivity. Let's take a quick look at them. Export emails. You can now export emails in the .eml file format

    • Next Page