查询API - 概述

COQL，即CRM对象查询语言的缩写，允许用户编写类似SQL的查询来从Zoho CRM获取记录。就像SQL使用表名一样，Query API在查询中使用模块和字段API名称。
虽然Search API允许模块特定的搜索，但Query API允许您从通过查找字段链接的跨模块中检索记录，从而建立连接。

目录

语法和支持的子句

Query API支持SELECT查询以及以下子句，您可以使用这些子句根据条件应用并从模块中检索记录。在SELECT列中，您必须使用字段API名称作为列名。

• SELECT - 这个语句是用来选择你想在响应中接收的字段。你可以在查询的SELECT列中指定多达500个字段API名称。你可以使用字段元数据API来获取模块中字段的API名称，或者前往设置 > 开发者中心 > APIs和SDKs，然后点击API名称标签。从可用模块列表中选择所需的模块，并查找所需字段的API名称。
• WHERE - 这个子句用于指定过滤和获取记录的条件或标准。您可以在此子句中包含多达 25个条件。确保正确地将条件括在括号中以获得期望的结果。
• FROM - 这个子句用于指定你想从哪个模块的API名称中检索记录。要从子表单中检索记录，请指定子表单模块的API名称。同样，对于具有多选查找字段的查询，查询到链接模块。
• ORDER BY - 使用此子句根据特定字段对响应中的记录进行排序，可以是升序或降序。默认的排序是根据记录ID的升序排列。
• LIMIT 和 OFFSET - LIMIT子句用于指定您希望在响应中接收的匹配记录的数量。默认值为200，最大值为2000。
  OFFSET用于对记录进行分页。例如，如果您将此值设置为10，那么系统将跳过前十个匹配的记录，并从第11个索引开始检索其他记录。
  在COQL中，语法是LIMIT offset, limit。第一个值是偏移量，而下一个值是限制。
• GROUP BY - 使用此子句从表中检索数据，通过在查询中指定字段API名称作为条件并对其进行分组。它可以帮助您有效地过滤和组织记录，并根据一个或多个列将查询结果作为对象分组在响应中。通常，您可以将此子句与聚合和非聚合函数一起使用。

语法

这是一个COQL查询的语法。

SELECT field_api_name1, field_api_name2
                    FROM base_module_api_name
                    WHERE field_api_name comparator logical_operator field_api_name comparator
                    ORDER BY field_api_name ASC/DESC
                    LIMIT offset, limit

这是一个示例SQL查询和它的等价COQL查询。在查询中，我们想要从Leads模块获取Last_Name，Created_Time字段。WHERE子句有条件。此查询根据Created_Time和记录ID的升序对响应中的记录进行排序，如ORDER BY子句中所指定的。偏移量是10，限制是2，意味着跳过前10个匹配的记录，然后在响应中检索接下来的两个记录。 
 

SELECT Last_Name, Created_Time
                    FROM Leads
                    WHERE Last_Name IS NOT NULL 
                      AND Created_Time >= '2019-02-19T12:57:55+05:30'
                    GROUP BY Last_Name, Created_Time
                    ORDER BY Created_Time, id ASC
                    LIMIT 10 OFFSET 2;

等价的COQL查询

{
        "select_query" : "select Last_Name, Created_Time from Leads where (Last_Name is not null and Created_Time >= '2019-02-19T12:57:55+05:30')  group by Last_Name, Created_Time order by Created_Time, id asc limit 10, 2"
        }

Response

{
        "data": [
            {
                "Last_Name": "Smith",
                "Created_Time": "2019-11-26T12:09:48+05:30"
            },
            {
                "Last_Name": "Gerald",
                "Created_Time": "2019-11-26T12:10:43+05:30"
            }
        ],
        "info": {
            "count": 2,
            "more_records": true
        }
    }
    

字段和标准

查询记录的主要目的是根据一些条件进行筛选。查询API允许您在WHERE子句中对各种字段应用多个条件。当满足条件时，匹配的记录将在响应中呈现。

考虑这个简单的查询。

{
        "select_query":"select Last_Name, Company, Lead_Status from Leads where (Lead_Status = Contacted and Last_Name is not null) limit 2 "
    }
    

在这个查询中，Last_Name，Company和Lead_Status是我们希望在响应中检索的Leads模块中字段的API名称。
WHERE子句包含了Lead_Status必须为Contacted，且Last_Name不能为空的条件。=和is not null是各自字段的比较符。and是应用于这些条件的组操作符。

就像这样，你的WHERE子句中最多可以有25个条件。也就是说，如果你的WHERE子句看起来像((A和B)和C)，这意味着在三个字段或相同的字段上应用了三个条件/标准。这样，你可以在WHERE子句中的不同字段或相同字段上应用多达25个条件。

每种字段类型（数据类型）都可以使用其自己的一套比较器。请参考通过COQL查询获取记录页面，了解每种字段类型的详细信息和示例。

别名支持

你可以在上面的回应中看到，键名很长。如果你想让它们变短，或者有对你来说更有意义的名字，你可以在COQL中使用别名支持。在你的查询中使用关键字AS（不区分大小写）来自定义回应中的键名。以下是一个示例。

{
    "select_query":"select 'Account_Name' AS 'Account id','Account_Name.Account_Name' as 'Account Name','Account_Name.Parent_Account' as 'Parent Account id','Account_Name.Parent_Account.Account_Name' As 'Parent Account Name' from Contacts where (Account_Name.Parent_Account.Account_Name = 'King') limit 1"
    }

Response

{
    "data": [
        {
            "Account id": {
                "id": "3652397000000624046"
            },
            "Account Name": "Zylker",
            "Parent Account id": {
                "id": "3652397000000190102"
            },
            "Parent Account Name": "King",
            "id": "3652397000000269089"
        }
    ],
    "info": {
        "count": 1,
        "more_records": true
    }
}

GROUP BY 和聚合函数

如在语法和支持的子句部分中所讨论的，GROUP BY子句是为了有效地过滤和组织记录，并根据一个或多个列将查询结果作为响应中的对象进行分组。您可以在聚合和非聚合函数上使用GROUP BY子句。

聚合函数

在Zoho CRM中使用COQL API的聚合函数的优势在于，它们可以直接在CRM中进行强大的数据分析。像SUM()、AVG()、COUNT()、MIN()和MAX()这样的聚合函数使您能够对数据进行计算，例如查找总计、平均值和其他统计度量。
这种功能有助于生成洞察和报告，无需将数据导出到外部工具，从而提高CRM环境中的效率和决策过程。 
请参阅通过COQL查询获取记录页面，了解每个聚合函数的详细信息和示例。

分页

使用Query API，您可以使用LIMIT 0, 2000每次API调用检索最多2000条记录。这将获取符合WHERE子句中条件的前2000条记录。 
当您想获取更多记录时，可以在LIMIT子句中使用OFFSET。例如，LIMIT 2000, 1500将从2001索引处获取1500条记录，即，它跳过索引1-2000中的记录。
使用相同的条件，您可以分页最多1,00,000条记录。对于下一组记录，添加另一个条件id > {last_record_id}，并使用"AND"运算符，然后继续获取下一个1,00,000条记录。如果您的查询中有自定义排序，请相应地调整条件。在以下示例中，排序是基于Created_Time和ID字段进行的。

查询 1

{
"select_query" : "select Last_Name, Created_Time from Leads where Last_Name is not null order by Created_Time, id asc limit 0, 200"
}

当你使用上述查询并更改OFFSET的值（在98,000处），你可以检索从98,001-1,00,000索引的记录。 
记下响应中最后一条记录的创建时间和ID。要获取超过之前获取的1,00,000的记录，你必须构建一个查询来检索在1,00,000记录之后创建的记录，且其记录ID大于1,00,000的记录的ID。

查询 2

{
"select_query" : "select Last_Name, Created_Time from Leads where ((Last_Name is not null and Created_Time > '2019-11-26T12:14:52+05:30') and id > 3652397000001257649) order by Created_Time, id asc limit 0, 10"

}