Escribir consultas SOSL

• Describir las diferencias entre SOSL y SOQL.
• Buscar campos en varios objetos mediante consultas SOSL.
• Ejecutar consultas SOSL mediante el editor de consultas de Developer Console.

Nota

¿Su idioma de aprendizaje es español? En esta insignia, las validaciones de los retos prácticos de Trailhead funcionan en inglés. Las traducciones se incluyen entre paréntesis a modo de referencia. En su Trailhead Playground, asegúrese de (1) cambiar la configuración regional a Estados Unidos, (2) cambiar el idioma a inglés y (3) copiar y pegar únicamente los valores en inglés. Siga las instrucciones descritas aquí.

Consulte la insignia Trailhead en su idioma para obtener más información sobre cómo aprovechar la experiencia de Trailhead en otros idiomas.

Diferencias y similitudes entre SOQL y SOSL

Como en el caso de SOQL, SOSL permite buscar registros de su organización para obtener información específica. A diferencia de SOQL, que solo puede consultar un único objeto estándar o personalizado cada vez, una sola consulta SOSL permite buscar todos los objetos.

Otra diferencia es que SOSL establece la coincidencia de los campos en función de una palabra coincidente, mientras que SOQL establece una coincidencia exacta de forma predeterminada (si no se usan comodines). Por ejemplo, la búsqueda de 'Digital' en SOSL devuelve registros cuyos valores de campo son 'Digital' o 'The Digital Company', pero SOQL devuelve solamente registros con valores de campo 'Digital'.

SOQL y SOSL son dos lenguajes independientes con una sintaxis diferente. Cada lenguaje tiene un caso de uso distinto:

• Use SOQL para recuperar registros para un solo objeto.
• Use SOSL para buscar campos en varios objetos. Las consultas SOSL permiten buscar la mayoría de los campos de texto de un objeto.

Requisitos previos

En el caso de algunas consultas de esta unidad, se espera que la organización tenga cuentas y contactos. Si no ha creado datos de ejemplo en la unidad sobre SOQL, cree datos de ejemplo en esta unidad. En caso contrario, puede omitir la creación de datos de ejemplo en esta sección.

1. En Developer Console, abra la ventana de ejecución anónima desde el menú Debug (Depurar).
2. Inserte el siguiente miniprograma en la ventana y haga clic en Execute (Ejecutar).

// Add account and related contact
Account acct = new Account(
    Name='SFDC Computing',
    Phone='(415)555-1212',
    NumberOfEmployees=50,
    BillingCity='San Francisco');
insert acct;
// Once the account is inserted, the sObject will be 
// populated with an ID.
// Get this ID.
ID acctID = acct.ID;
// Add a contact to this account.
Contact con = new Contact(
    FirstName='Carol',
    LastName='Ruiz',
    Phone='(415)555-1212',
    Department='Wingo',
    AccountId=acctID);
insert con;
// Add account with no contact
Account acct2 = new Account(
    Name='The SFDC Query Man',
    Phone='(310)555-1213',
    NumberOfEmployees=50,
    BillingCity='Los Angeles',
    Description='Expert in wing technologies.');
insert acct2;

Uso del editor de consultas

Developer Console incluye una consola de editor de consultas, la cual permite ejecutar consultas SOSL y ver los resultados. El editor de consultas es un método rápido para inspeccionar la base de datos. Además, es una buena forma de probar sus consultas SOSL antes de agregarlas al código Apex. Si usa el editor de consultas, debe especificar solamente la declaración SOSL sin el código Apex que la rodea.

Vamos a intentar ejecutar el siguiente ejemplo de SOSL:

1. En Developer Console, haga clic en la ficha Query Editor (Editor de consultas).
2. Copie y pegue lo siguiente en el primer cuadro debajo del editor de consultas y, a continuación, haga clic en Execute (Ejecutar).

FIND {Wingo} IN ALL FIELDS RETURNING Account(Name), Contact(FirstName,LastName,Department)

Todos los registros de cuenta y contacto de su organización que cumplan los criterios se muestran en la sección de resultados de la consulta en forma de filas con campos. Los resultados se agrupan en fichas para cada objeto (cuenta o contacto). La consulta SOSL devuelve registros con campos cuyos valores coinciden con Wingo. Según los datos de ejemplo, dado que tan solo un contacto tiene un campo con el valor Wingo, se devuelve este contacto.

Nota

La consulta de búsqueda en el editor de consultas y la API se debe incluir entre corchetes ({Wingo}). Por el contrario, la consulta de búsqueda en Apex se incluye entre comillas simples ('Wingo').

Sintaxis de SOSL básica

Esta es la sintaxis de una consulta de SOSL básica en Apex: 

FIND 'SearchQuery' [IN SearchGroup] [RETURNING ObjectsAndFields]

Recuerde que en el Editor de consultas y en la API, la sintaxis es algo diferente:

FIND {SearchQuery} [IN SearchGroup] [RETURNING ObjectsAndFields]

SearchQuery es el texto que buscar (una sola palabra o una frase). Los términos de búsqueda se pueden agrupar con operadores lógicos (AND, OR) y paréntesis. Además, los términos de búsqueda pueden incluir caracteres comodín (*, ?). El carácter comodín * coincide con cero o más caracteres en el centro o al final del término de búsqueda. El carácter comodín ? coincide solo con un carácter en el centro o al final del término de búsqueda.

No se aplica la distinción entre mayúsculas y minúsculas a las búsquedas de texto. Por ejemplo, la búsqueda de Customer, customer o CUSTOMER devuelve los mismos resultados.

SearchGroup es opcional. Es el ámbito de los campos en el que se va a buscar. Si no se especifica, el ámbito de la búsqueda predeterminada equivale a todos los campos. SearchGroup puede aplicar uno de los siguientes valores:

• ALL FIELDS (TODOS LOS CAMBIOS)
• NAME FIELDS (CAMPOS DE NOMBRE)
• EMAIL FIELDS (CAMPOS DE CORREO ELECTRÓNICO)
• PHONE FIELDS (CAMPOS DE TELÉFONO)
• SIDEBAR FIELDS (CAMPOS DE BARRA LATERAL)

ObjectsAndFields es opcional. Es la información que se devuelve en el resultado de la búsqueda (lista de uno o varios sObjects y, en cada sObject, lista de uno o varios campos con valores opcionales mediante los que filtrar). Si no se especifica, los resultados de la búsqueda contienen los Id. de todos los objetos encontrados.

Palabras individuales y frases

SearchQuery contiene dos tipos de texto:

• Palabra individual: una sola palabra, como test o hello. Las palabras de SearchQuery se delimitan mediante espacios, puntuación y cambios de letras a dígitos (y viceversa). En el caso de las palabras, nunca se aplica la distinción entre mayúsculas y minúsculas.
• Frase: conjunto de palabras y espacios incluidos entre comillas dobles, como "john smith". Se pueden combinar varias palabras mediante operadores lógicos y de agrupación para formar una consulta más compleja.

Ejemplos de búsquedas

Para saber cómo funciona la búsqueda mediante SOSL, vamos a trabajar con distintas cadenas de búsqueda para ver en qué se basa el resultado de los datos de ejemplo. En esta tabla se incluyen varias cadenas de búsqueda de ejemplo y los resultados de la búsqueda mediante SOSL.

Ejemplo de SOSL en Apex

En este ejemplo se muestra cómo ejecutar una consulta SOSL en Apex. Primero, se asigna la variable soslFindClause a la consulta de búsqueda, que se compone de dos términos (Wingo y SFDC) combinados mediante el operador lógico OR. Para hacer referencia a esta variable local, la consulta SOSL coloca primero dos puntos, lo que se conoce como vinculación. La consulta SOSL resultante busca los términos Wingo o SFDC en cualquier campo. Este ejemplo devuelve todas las cuentas de ejemplo, ya que cada una tiene un campo con una de las palabras. Los resultados de la búsqueda con SOSL se devuelven como una lista de listas. Cada lista contiene un conjunto de los registros devueltos. En este caso, la lista tiene dos elementos. En el índice 0, la lista contiene el conjunto de cuentas. En el índice 1, la lista contiene el conjunto de contactos.

Ejecute este miniprograma en la ventana de ejecución anónima de Developer Console. A continuación, revise el registro de depuración para verificar que se devuelven todos los registros.

String soslFindClause = 'Wingo OR SFDC';
List<List<sObject>> searchList = [FIND :soslFindClause IN ALL FIELDS
                    RETURNING Account(Name),Contact(FirstName,LastName,Department)];
Account[] searchAccounts = (Account[])searchList[0];
Contact[] searchContacts = (Contact[])searchList[1];
System.debug('Found the following accounts.');
for (Account a : searchAccounts) {
    System.debug(a.Name);
}
System.debug('Found the following contacts.');
for (Contact c : searchContacts) {
    System.debug(c.LastName + ', ' + c.FirstName);
}

Más información...

Puede filtrar, reordenar y limitar los resultados devueltos de una consulta SOSL. Dado que las consultas SOSL pueden devolver varios sObjects, estos filtros se aplican en cada sObject en la cláusula RETURNING.

Para filtrar los resultados de SOSL, agregue condiciones en la cláusula WHERE para un objeto. Por ejemplo, esto solo devuelve cuentas cuyo sector es Apparel (Textil): RETURNING Account(Name, Industry WHERE Industry='Apparel').

Además, se permite la ordenación de los resultados para un sObject mediante la adición de ORDER BY para un objeto. Por ejemplo, esto tiene como resultado que las cuentas devueltas se ordenen por el campo Name (Nombre): RETURNING Account(Name, Industry ORDER BY Name).

El número de registros devueltos se puede limitar a un subconjunto de registros. En este ejemplo las cuentas devueltas se limitan solo a 10: RETURNING Account(Name, Industry LIMIT 10).