About Value Search
Value Search is a new feature in Studio 3T. It allows users to perform wide-ranging searches on the values stored in a collection, database, or server. By default, for any value search, Studio 3T will scan every document. It will search for a text (or regular expression) match in every field value that exists in the document.
This includes all embedded documents and arrays. Value Search will then report back on what matched. This will include the path to the matched field.
Starting Value Search
To open a Value Search view, select a collection, database, or server in the Connection Tree in the Studio 3T window. Then either select File > Open Value Search or right-click on the selected item and choose Open Value Search.
The Value Search view will open. The tab title reflects where any future search take place.
Below that are three indicators. The first shows the server in use. The second is a selector for the which database to search. The third is a selector for which collection, within that database, to search. If you select a server for your Value Search, the second selector will default to <all databases> and the collection selector will be set to <all collections>.
Selecting a database when opening Value Search, or adjusting the database selector to a particular database will enable the collections selector.
This restricts the search to the selected database, but can still search <all collections> within that database.
Selecting a collection when opening Value Search, or adjusting the Collection selector to a particular collection will further restrict the search to that particular collection.
Performing a Value Search
Once you have selected the scope of your Value Search, you can enter a search term in the search field. The search term can be plain text or a regular expression.
If you wish the search to be case-sensitive, check the Match Case field to toggle case-sensitive searches on.
Check the RegEx field to toggle the use of Regular Expressions if you want to use a regular expression as a search term. Value Search’s regular expressions use the Java regular expression engine. Refer to Regular Expressions In Studio 3T for a reference to the formats of regular expression accepted.
We will examine the Advanced Options toggle later in this article.
The search term is, by default, a match with plain text. The text will match anywhere in a value. For many use cases, this is sufficient to home in on relevant fields. Use regular expressions where you want more defined precision in your matches.
Value Conversion
Note that when searching, values in the database documents which are not string types are converted to strings.
For example, numbers present as strings so a value search for 10 as plain text would match with 10, 100, 90.10 stored as numbers. It would also match with 10/6/22, a stored date converted to a string, as well as K100 (a string which contains a number).
Plain Text searches will always simply match the sequence of characters.
Viewing Value Search Results
Pressing the Return key in the search field or clicking on the Search button begins the search. You can follow how the search is doing in the lowe left of the view, where a progress meter and count of matches is shown. Also in the lower left is a “cancel” button (red circle with cross) which can terminate the search early.
Each match is displayed in the five-column table. Whilst you can interact with the table as the search runs, the search term controls are only enabled when the search is complete. You will have to stop the search, or wait for it to finish, before you can adjust those settings.
Each row is made up of five elements, each one related to a match found by Value Search:
Database: The name of the database where this match is.
Collection: The name of the collection where this match is.
_id: The _id field of the document where the match is.
Path: The path, from the document’s root, to the field where the match is. Paths display in Studio 3T format. This is a field name that is optionally followed by a > and either a number or another field name. A number usually represents the index value of an array. This repeats as needed.
Value: The value of the field in which a match is found.
The Database, Collection, _id, and Path allow you to locate precisely where the value match is.
The particular parts of Value that match are shown with a yellow background.
Viewing Matched Documents
For any match displayed in Value Search, you have two options.
- Double-Clicking the row will open the document containing the match in the Document JSON Viewer. You can only view the document here.
- Right-Clicking on the row will display the context menu for the row.
View Document, like double-clicking, opens the document in the collection using the Document JSON Viewer.
Open in Collection Tab will open a new Collection Tab with a query that selects only the matched document. From the Collection Tab, you can edit fields inline or view and edit the matched Document.
Advanced Options
Advanced options enable an extra level of control over how Value Search examines collections.
Before scanning any collection’s documents, Value Search runs a query which will select the documents it searches. By default, this is an empty query which returns all documents in the collection. The Advanced options let you control what that query is. This allows you to focus search on specific fields, reduce the number of documents examined, or pre-sort the results.
You can create queries using the Collections Tab and Visual Query Builder. They can then be copy and pasted, or saved and loaded, into the Advanced options.
Query
The Query field takes a MongoDB query document specification. It is a pre-filtering stage for the documents in the value search. For example, if you only want to search documents where the country field is not “United States”, then you can set the query to:
{ “country”: { $ne: “United States” } }
Any document where the country field is not “United States” will move on to the Value Search. Note that in this example, the result of the query would also return documents that did not have a country field at all (because null is not equal to United States). When doing a Value Search with a query on multiple collections, remember that the same query will run on all the collections. If the query fails to match any documents – for example, because a field is being present in a collection – no fields in that collection will go on to be in the value search.
Projection
The Projection field is useful in reducing the number of fields that pass into the Value Search. By selecting fields for inclusion or exclusion, you can make sure that Value Search is retrieving less of the documents, but still thoroughly searching the rest of the fields. For example, if your collections have a large text record attached called notes which you don’t want searched, setting the Projection to { notes: 0 } will exclude that one field from the Value Search. Again, this will be apply to all collections in scope.
Skip and Limit
Skip and Limit will, as they do in the Collections Tab and other queries, skip over a number of documents and then limit the number of documents returned by the query. If you want to only search 1000 documents in a collection, starting after the first 2000 documents, then setting Skip to 2000 would skip the first 2000 documents and setting Limit to 1000 would restrict the number of returned documents to a maximum of 1000.
Sort
Use the Sort field in Advanced options if you have want the results to appear in a particular order. This will pre-sort the documents before they are passed on to the Value Search. Again, it takes the same Sort specification as used in the Collections tab query bar and Visual Query Builder.
That is a JSON list of field names with the values -1 or 1 to determine ascending or descending sorting for that field. Setting the Sort field to { birthdate: 1, username: 1} will sort the documents by ascending birthdate field value and ascending username text field value.
Here, we are doing a value search that focusses on just the name and username fields, with a window that scans 50 documents (after skipping ten) from a collection sorted by birthdate and username. As you can see, this limits the results.
