Help: SoqlX v4.1

Contents:



Login

SoqlX uses the API to connect to Salesforce. Depending on how your admin configured it, you may need to use your api security token in addition to your password to login. If so just add the token to the end of your password. e.g. if your password is `beerisnice` and your security token is `abv123`, enter `beerisniceabv123` as the password.

If you get a LOGIN_MUST_USE_SECURITY_TOKEN error means you most likely forgot to include your security token (search for security token in the Salesforce.com online help for more info)

Keychain: Let SoqlX securely store your login credentials on the keychain, you'll be much happier. Next time you run SoqlX it'll remember your username & password for you. If you have multiple logins, it can remember all of them.

Sandbox: Use the Server drop down to switch between production and sandbox logins. If you use the custom domains feature You can click the + sign next to the server drop down to add additional servers to the list.

Login: Using the File menu you can choose login and open more SoqlX windows, these can be for the same user, or for different users.


Queries

To execute a SOQL query, type the query into the box at the top, click Query (or Query All). The results will appear in the table, or for count queries in the bottom left hand corner.
The Query All button will run the query with the QueryAll API, which includes soft deleted and archived results. (This is the equivalent of ALL ROWS in Apex).

As you are typing the query SoqlX can supply completions for SObject, field and function names. The options will popup when the cursor is at the end of the word, select an item to have it inserted into the query. The best completions are available when the query is structurally valid, start with a a base 'select id from account' query and then go back and type in the remaining items in the select clause for the best experience.

When the auto completions popup is visible, you can continue typing and the selection will adjust accordingly. You can use the cursor up / down and page up / down keys to move through the list, and press enter to select the currently highlighted item. You can use escape to close the popup without making a selection. You can also use the mouse to navigate around the popup. If you closed the popup but want it back you can press F5 to re-open the popup.

The completions are context aware, so for example if you're select a field for a group by clause, it will only show fields that are actually groupable by. If there's an error in the query then the relevant part of the query will be underlined in yellow and you can click on that text to see the error details. Errors can include things like the object or field name is not valid as well as syntax errors in the query. SoqlX is not aware of everything that makes a query invalid, so at times it will not show an error but when the query is executed an error is returned. However it should never say that a valid query has an error.

By default the keywords in the query will be automatically converted to upper case as you type. If you don't want this to happen you can turn it off in the preferences. You can also completely disable the syntax highlighting and auto completions from the preferences as well.

Completions are also available for SOSL queries, and work exactly the same way.

SOQL-R is supported, so you can do both queries that access foreign key relationships (like accessing account from a contact), and also aggregate child queries (like select accounts, and the contacts for each account). Double click the magnifying glass to expand the 2nd query table at the bottom, showing the child rows for that particular parent row.

You can sort the results by clicking the column headers.

If you queried the Id column then you can edit data inline. Double click the cell and type in your new value. When the cell looses focus the record in Salesforce will be updated. You can also check the deleted checkbox and hit the delete button to delete row(s). Click the Delete column header to quickly toggle the checkbox on all rows.

Using the File menu, you can save the query results to a CSV file, or save the text of the query itself.

The recent queries window will show you the last 10 queries you've executed. Double click a query to copy it to the SOQL query textbox. Watch the recent queries list animate the changes as you run new queries!.

SOSL queries work exactly the same way, type the SOSL query into the query box and hit query.

The list of SObjects & fields appear in the list view on the left hand side. Double click an SObject to automatically create a query to select all the fields. The Details button at the top of the window will open/close the details window which shows all the metadata about the currently selected SObject or field. The status footer at the bottom of the window will also report the progress of the metadata fetching.
The object names will appear in gray while SoqlX is fetching (aka Describing) the metadata for your organization. As the metadata is loaded the object names will change to a brighter color. The 'Refresh Metadata' option in the menu can be used to reload all the metadata. (e.g. if you added a new custom object or field).

The search box above the SObject list can be used to filter & highlight entries in the list view.

Schema

Apex

Click the Apex button in the toolbar to switch to the anonymous apex window. From here you can enter your apex, hit `Execute` and see the debug output in the bottom right area. If there's an error in your apex it'll be highlighted. The different log level options in the middle can be used to control the amount of debug logging generated.

You can use the Save/Open File menu options to Save and Load your anonymous apex script.



Preferences


The Preferences window can be opened by selecting Preferences from the SoqlXplorer menu.
If "Check for updates" is enabled, SoqlX will check to see if there's an update available when you launch it. It does this check at most once a day. If there is an update available it'll show you the details and offer to install it.

The Edit Text Font/Size preference adjusts the font used in the Query text area, the Apex text area and the Apex log.

Advanced

As of v3.1 it has the ability to launch SoqlX with an existing SessionID from the command line or other applications. This is aimed at developers who want to integrate SoqlX more closely with their tools. For example integrating it with Salesforce-DX (See this issue for details).

The custom URL schema is `soqlx` and it expected to receive a server name and session Id.

    soqlx://<ServerHostGoesHere>/sid/<SessionIdGoesHere>
        
    This can be used from the command line using the open command, e.g.
    open 'soqlx://na45.salesforce.com/sid/00D300000000QSf!AQwAQBW2zsIkQE_tIUx33T9StPuMlZ5X7hpcFWYXjJ3xG7Ckhb7zLEThisIsnotARealSessionID'
    
    SessionIDs typically have shell metachars in, hence the ' quoting used.



Got questions, or suggestions for new features, catch me on twitter, or log an issue in the Github project.

Help: SoqlX v4.6 v : November 15, 2021