Luminate Online

Usage

Returns a filtered set of records of a particular type from the Luminate Online database.

A Query request must include a query string in the general form:

  select Field1 [, Field2, Field3, ...] from RecordType [where Criteria]

The RecordType is the name of an element in the Luminate Online WSDL that extends the Record base type, such as Constituent or Donation. The field list should be a list of element names selected from the WSDL schema definition for that type.

Not all record types defined in the WSDL support the Query operation. You can use the DescribeRecordType operation to check this.

The [where Criteria] clause may include one or more boolean phrases that reference fields in the requested record type, similar to the format of a simple WHERE clause in an SQL query.

Not all fields may be used in the criteria clause. Once again, you can use the DescribeRecordType operation to verify which fields may be used.

As with all operations, a valid SessionId session token returned by the Login operation is required in the header of the request.

The response consists of zero or more records of the requested type. A single response contains a maximum of 1,000 records. To ensure that you have retrieved all records for a particular query, your client needs to implement the following logic:

Make an initial request, optionally specifying a PageSize if you want to retrieve fewer than 1,000 records at a time.
If the number of records in the response is equal to the requested page size, submit a second request with the same query string and page size as the initial request, along with Page parameter of 2.
Continue making requests, incrementing the page each time, until the number of records in the response is fewer than the requested page size.

Only two specific usages of the Query operation are supported at this time:

selecting all records from a reference table for performing lookups in the middleware, such as:
```
select CampaignId, Title from DonationCampaign
```
looking up additional information about a specific record by primary key, such as:
```
select ConsId, UserName, HomeAddress from Constituent where ConsId = 123
```

Wildcards are supported in the select clause in in two ways. An asterisk by itself returns a subset of top-level fields for the selected records:

select * from Constituent where ConsId = 123

An asterisk appended to a nested element returns a subset of fields within that element:

select Donor.* from Donation

Note that the asterisk is optional in the latter case. This query returns the same result:

select Donor from Donation

A wildcard query does not return all fields in an element. Instead, it only returns a set of the most commonly used fields. You can use the field-level metadata returned by the DescribeRecordType operation to determine which fields are part of the wildcard set for a particular element.

Note: Timestamp fields in the Luminate Online database are stored with millisecond precision. The Query operation returns values using one-second precision, which may cause unexpected results. For example, the query: select * from Refund where Payment.Modifydate > 2009-10-21T01:10:16Z may return a record with the apparently-equal value 2009-10-21T01:10:16Z because the actual stored value includes a milliseconds component not shown.

Request Parameters

QueryString: string; A value is required; The Query to execute
Page: positiveInteger; A value is required; The index of the page of results to retrieve.
PageSize: positiveInteger; A value is required; The number of records to return per page

Response Parameters

The response may contain zero or more response elements

Record: Record; Multiple values allowed; A constituent record containing at least ConsId, MemberId and PrimaryEmail for identification purposes.

Faults

Example SOAP request


<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ns3:Session xmlns:ns3="urn:soap.convio.com" soapenv:mustUnderstand="0">
         <ns3:SessionId>e96ce3db61a80642510225a783540f6dcb6e702d:JSESSIONID=abcMZ5dmWgZeidZtyWZ3r:10000100:2008-12-01T18:13:45.691Z</ns3:SessionId>
      </ns3:Session>
   </soapenv:Header>
   <soapenv:Body>
      <ns3:Query xmlns:ns3="urn:soap.convio.com">
         <ns3:QueryString>select ConsId from Constituent where ConsId = 1001482</ns3:QueryString>
         <ns3:Page>1</ns3:Page>
         <ns3:PageSize>3</ns3:PageSize>
      </ns3:Query>
   </soapenv:Body>
</soapenv:Envelope>

Example SOAP response


<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <QueryResponse xmlns="urn:soap.convio.com" 
	     xmlns:ens="urn:object.soap.convio.com" 
	     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Record xsi:type="ens:Constituent">
            <ens:ConsId>1001482</ens:ConsId>
         </Record>
      </QueryResponse>
   </soap:Body>
</soap:Envelope>