Create SOQL Queries in Apex Classes

Learning Objectives

After completing this unit, you'll be able to:

• Create a SOQL query in a method.
• Manipulate data returned by a SOQL query.

Follow Along with Trail Together

Want to follow along with an expert as you work through this step? Take a look at this video, part of the Trail Together series on Trailhead Live.

(This clip starts at the 17:32 minute mark, in case you want to rewind and watch the beginning of the step again.)

Introduction

Now that you understand the basics of a SOQL query, you can apply your knowledge of formula fields to SOQL queries.

Our query is pretty simple: SELECT FirstName, LastName FROM Contact

Now we need an object to store the resulting data in. Because SOQL queries always return data in the form of a list, we create an Apex list. As you learned in Apex Basics for Admins, to declare a list you need a few things: the List reserved word, the data type (in < > characters), and a name for the new list. For this query, the data type is Contact and we name the new list listOfContacts. The list declaration looks like this:

List<Contact> listofContacts

To assign the results of the query to the new list, we put an assignment operator, the equals symbol ( = ), between the list declaration and the query, like this:

List<Contact> listofContacts = [SELECT FirstName, LastName FROM Contact];

Notice the syntax. The query is enclosed in square brackets [ ], and the statement ends with a semicolon ( ; ).

Let's try it out in the Developer Console. For testing purposes, we send the list of contacts to the Debug log so we can see how the code is working.

Test Your Code in the Developer Console

1. In the Developer Console, click Debug | Open Execute Anonymous Window.
2. In the Execute Anonymous window, assign the query results to the new list:

   List<Contact> listOfContacts = [SELECT FirstName, LastName FROM Contact LIMIT 2];

3. On the next line, send the listOfContacts list to the Debug log:

   system.debug(listOfContacts);

4. Click the Open Log checkbox.
5. Click Execute.
6. At the bottom of the Execution Log window, click the Debug Only checkbox.
   The first two items in the Debug log should look like this:

7. 

   If a query finds no results, it still returns a list, but the list is empty:

   [2]|DEBUG|()

What's Actually Happening Here?

When our code runs, first, it processes the query:

SELECT FirstName, LastName FROM Contact LIMIT 2

The query finds all Contacts and gets the first name and last name from each record. Then our code adds the selected data from those contact records to a list named listOfContacts.

Finally, on line 2, System.debug displays the contents of listOfContacts.

Run SOQL Queries in Apex

In the previous unit, you used the query editor to return data in a table. In this unit, you used the Execute Anonymous window to run a query and send the results to the debug log. That's great for now, but your users aren't going to be running queries in the Developer Console. You need a way to return data in the user interface of your org. Apex classes and methods are the way to do that. Let's explore how to run a SOQL query and manipulate its results in Apex.

We start by creating an Apex method in an Apex class. The Apex method runs our query to select the data we want.

1. In the Developer Console, click File | New | Apex Class.
2. Name the class ContactUtility and click OK.

3. The class opens, displaying code that declares the class and leaves space for the body of the class.

4. On line 2, add a method named viewContacts.

   public static void viewContacts(){
   }

5. On line 3, inside the viewContacts method, paste the code that runs the query and assigns the results to a new list:

   List<Contact> listOfContacts = [SELECT FirstName, LastName FROM Contact];

6. Save the class.

Now we have the data we want in the listOfContacts list. We'll use a for loop to iterate through the list, constructing the format we want for our output.

Using For Loops to Iterate Through a List

In Object-Oriented Programming for Admins, you learned how to process items in a list, one by one, using a for loop. Here, using a for loop, we combine the first and last name of each contact to form the contact's full name. First, let's create the loop, then we'll process each record within the loop.

To declare a for loop, we need a variable name, its data type, and the name of the list the loop iterates through.

In a for loop, we don't refer to specific objects directly. Instead, we create a variable to represent list items within the loop, one at a time. The variable serves as a placeholder for each item in the list. It can be any name you choose, but let's keep it simple. We'll use con. Then we need the variable's data type, which is Contact, and the name of the list, which is listOfContacts. All together, it looks like this:

Declare a For Loop

1. In the viewContacts method, after the SOQL query, paste this code:

   for (Contact con : listOfContacts){
       //loop body
   }

2. Save the class.

We've queried the database (1), selected data, stored the data in a list (2), and created a for loop (3).

Next, within the loop, we process the items in the list. Ultimately, we want to display each contact in listOfContacts in this format:

First Name: <contact's first name>, Last Name: <contact's last name>

To reference a field for an item in a list, use dot notation to specify the object and its field (object.field). For example, refer to the FirstName field of a Contact object in the listOfContacts list by putting a period (the “dot” in dot-notation) between con (the object variable) and FirstName (the field), like this:

con.FirstName

The list contains separate first and last name fields. In Apex, we combine field values (and sometimes literal text too) by using concatenation. (You did some concatenating in Apex Basics for Admins.)

As a refresher, when you concatenate, field data is represented as object.field. Literal text is enclosed in single quotation marks. Don't forget to include spaces at the beginning and end of literal text where needed. Use the plus symbol ( + ) to combine fields or to combine a field and some literal text.

Let's fill in the body of our for loop. First, for every item in the listOfContacts list, we combine the FirstName and LastName in a new variable named fullname:

String fullName = 'First Name: ' + con.FirstName + ', Last Name: ' + con.LastName;

Notice the space between FirstName and LastName. The output should look like:

First Name: Angela, Last Name: Carter

not

FirstName:Angela,LastName:Carter

After the value for the fullName variable (data type: String) is assigned, we plug that variable into the debug statement on the next line:

system.debug(fullName);

Process List Items in the For Loop

1. In the viewContacts method, replace //loop body with this code:

   String fullName = 'First Name: ' + con.FirstName + ', Last Name: ' + con.LastName;
   system.debug(fullName);

2. Save the class.

Your code should look like this:

public class ContactUtility {
    public static void viewContacts(){
        List<Contact> listOfContacts = [SELECT FirstName, LastName FROM Contact];
        for (Contact con : listOfContacts){
            String fullName = 'First Name: ' + con.FirstName + ', Last Name: ' + con.LastName;
            system.debug(fullName);
        }
    }
}

Now that we have a class, a method, and a SOQL query ready to go, let's run the code and see if it works. To run Apex code in the Execute Anonymous window, we specify the class and method using dot-notation.

1. Open the Execute Anonymous window.
2. In the Enter Apex Code window, replace the existing code with this code:

   ContactUtility.viewContacts();

3. Verify that Open Log is checked.
4. Click Execute.
5. Select Debug Only.

The first six rows of your results should be:

Look at that! With SOQL, a for loop, and concatenation, you retrieved contact data, assigned the data to a list, iterated through the list, and generated the expected results. Way to go!

Resources

• Blog: Women Code Heroes: Oh... for the Love of For Loops
• Apex Developer Guide: Classes
• Apex Developer Guide: Class Methods