SOQL Fields function to investigate Schema - what is the purpose

Question

Salesforce introduces the new FIELDS() function allowing to do things like this:

SELECT FIELDS(ALL) FROM Account LIMIT 200

Instead of this:

SELECT Id, Name FROM Account LIMIT 200

This seems useful in cases where we'd construct a SOQL call based on a parameter of a function, so that now we don't have to do that. Salesforce gave an explanation of why there is such a function:

Why: In previous versions of SOQL, retrieving fields meant specifying all the names of all the fields you wanted to retrieve. Typically, this required first making an API call to describe the object to get the list of fields (or using the Object Manager) and then laboriously constructing a SOQL query to select all those fields. Further, such a query could exceed the query character limit for large complex queries that retrieve lots of data. The new FIELDS() function lets you select all the fields without knowing their names in advance. This eliminates the need for a round-trip to the server to prepare a SOQL statement, eliminates the need for research and a lot of typing, simplifies query statements, and makes it much easier to explore the shape of your objects.

What I can't get my head around is the use case mentioned: Typically, this required first making an API call to describe the object to get the list of fields (or using the Object Manager) and then laboriously constructing a SOQL query to select all those fields.

Could anyone explain perhaps with an example what is meant by making an API call in this example?

Answer 1

The mention of "API call" here is quite literal. This information/feature is mainly targeted at people using the REST API (and I suppose the SOAP API as well...). Generally, from somewhere outside of Salesforce as opposed to on-platform in Apex

You'd previously need to

1. make a call to https://yourSalesforceDomain.my.salesforce.com/services/data/v54.0/sobjects/Account/describe to be able to enumerate the fields on the SObject
2. then a second call to https://yourSalesforceDomain.my.salesforce.com/services/data/v54.0/query/?q=<long, url-encoded string representing your query>

The information you linked to mention, in passing, a character limit for queries. The exact limit is kinda hard to pin down and has changed over the years. Current documentation suggests that the overall query itself is limited to 100k characters, and the WHERE clause limited to 4000 characters (with logical operators being removed for SOSL queries).

If you have enough fields on an object, it's possible that you'd exceed that limit (or run into the REST API url length limit that I found a few years back).

So FIELDS() can be a godsend.

This two-api-call structure also has an analogue in Apex. I've broken it out into 4 lines to make it easier to read, but this could technically be done as a one-liner (though please don't try to cram this amount of work into a single statement)

// get the sobject describe information to get at the fields
SObjectDescribeResult sobjDesc = Account.SObjectType.getDescribe();

// process the describe result to get the fields
// here, I'm just being lazy and getting the api names from the keyset of the map
List<String> accountFields = new List<String>(sobjDesc.fields.getMap().keySet());

// use the fields to build a dynamic soql query
String preparedQuery = String.format('SELECT {0} FROM {1}', new List<Object>{
    String.join(accountFields, ', '), // Id, Name, Description, CustomField__c ...
    sobjDesc.getName()
});

// execute the query
List<SObject> results = Database.query(preparedQuery);

FIELDS() can also be used in Apex, but only FIELDS(Standard). At any rate though, FIELDS() saves us a considerable amount of work.

List<SObject> results = Database.query('SELECT FIELDS(Standard) FROM Account');

The savings are pretty much as drastic as that when making API calls.