QueryMore

From API Documentation

Jump to: navigation, search

Use queryMore() to request additional results from a previous query() call. If your initial query() call returns more than 2000 results, you can use queryMore() to query for more the additional results

Contact Zuora Global Support to enable queryMore() functionality.

Note: As of version 20.0, Zuora will now expire queryMore() cursors after 15 minutes of activity, regardless of the API version that you are using.

Contents

Syntax and Argument

To use query queryMore(), you first construct a query() call. By default, the query() call will return up to 2000 results. If there are more than 2000 results, query() will return a boolean "done", which will be marked as false, and a queryLocator, which is a marker you will pass to queryMore() to get the next set of results.

Using This Call

This call sends a request for additional results from an initial query() call. If the initial query() call returns more than 2000 results, you can use the queryLocator returned from query() to request the next set of results. By default, 2000 results will be returned with the queryMore() call, but this can be changed by setting batchSize in QueryOptions.

You can set the number of results to return by setting BatchSize in SOAP header. It can be a number between 0 and 2000. Setting to 0 is the default setting, which will return 2000 results.

Example

Step 1: Make query() Call

A typical request could be: 

  SELECT Id FROM InvoiceItem

Normally, Zuora would return either 100 results (version 5.0 and below) or 2000 results (version 6.0 and greater). However, if your query exceeds this limit, you can now use queryMore() to request the remaining results.


Here is an example that makes query, and requests that only 50 results be returned. 

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns2:SessionHeader>
            <ns2:session>x325DpHqCwv9ya830FxMUddETMcl5b16nul5pRcW972Ch_9_WAWSo7ofZDzto26ittQzDFX7RAxY6JIZe_5EpgyXaBiuD0EAr7uQTyjJWRC_oMNciUEId2SfM2guVUL0HafNkjAVj04D5cMaLlB27Q==</ns2:session>
        </ns2:SessionHeader>
        <ns2:QueryOptions>
            <ns2:batchSize>50</ns2:batchSize>
        </ns2:QueryOptions>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:query>
            <ns1:queryString>select id from invoiceitem</ns1:queryString>
        </ns1:query>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The resulting response would be: 

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns1:queryResponse xmlns:ns1="http://api.zuora.com/">
            <ns1:result>
                <ns1:done>false</ns1:done>
                <ns1:queryLocator>4028e69923eaaa2a0124069b5c887849-50</ns1:queryLocator>
                <ns1:records xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:InvoiceItem">
                    <ns2:Id>4028e6991f1b0aa5011f1c82a53a0054</ns2:Id>
                </ns1:records>
                <ns1:records xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:InvoiceItem">
                    <ns2:Id>4028e6991f1b0aa5011f1c82a56e0055</ns2:Id>
                </ns1:records>
<!-- ...48 more results... -->
                <ns1:size>1104</ns1:size>
            </ns1:result>
        </ns1:queryResponse>
    </soapenv:Body>
</soapenv:Envelope>

Step 2: Take queryLocator, issue queryMore() Call

With the queryLocator, you can now construct a queryMore() request which will return another set of results. Example queryMore() in this case would be: 

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns2:SessionHeader>
            <ns2:session>x325DpHqCwv9ya830FxMUddETMcl5b16nul5pRcW972Ch_9_WAWSo7ofZDzto26ittQzDFX7RAxY6JIZe_5EpgyXaBiuD0EAr7uQTyjJWRC_oMNciUEId2SfM2guVUL0HafNkjAVj04D5cMaLlB27Q==</ns2:session>
        </ns2:SessionHeader>
        <ns2:QueryOptions>
            <ns2:batchSize>50</ns2:batchSize>
        </ns2:QueryOptions>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:queryMore>
            <ns1:queryLocator>4028e69923eaaa2a0124069b5c887849-50</ns1:queryLocator>
        </ns1:queryMore>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

queryMore() returns a queryMoreResponse, almost identical to a queryResponse: 

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns1:queryMoreResponse xmlns:ns1="http://api.zuora.com/">
            <ns1:result>
                <ns1:done>false</ns1:done>
                <ns1:queryLocator>4028e69923eaaa2a0124069b5c887849-1050</ns1:queryLocator>
                <ns1:records xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:InvoiceItem">
                    <ns2:Id>4028e69923eaaa2a0124022c44522584</ns2:Id>
                </ns1:records>
                <ns1:records xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:InvoiceItem">
                    <ns2:Id>4028e69923eaaa2a0124022e1b8527cd</ns2:Id>
                </ns1:records>
<!-- ...48 more results...>
            </ns1:result>
        </ns1:queryMoreResponse>
    </soapenv:Body>
</soapenv:Envelope>

Step 3: Iteratively call queryMore()

Iteratively call queryMore() until done=true.

Retrieved from "http://apidocs.developer.zuora.com/index.php/QueryMore"