This page describes how to search for files with a specific label or field value applied.
Label field types
Google Drive label fields are strongly typed with each type supporting different indexing and search semantics. The following table shows the available data types.
Type | Label type options | Supported search operators |
---|---|---|
Text | TextOptions | is null, is not null, =, contains, starts with |
Long Text | LongTextOptions | is null, is not null, contains |
Integer | IntegerOptions | is null, is not null, =, !=, <, >, <=, >= |
Date | DateOptions | is null, is not null, =, !=, <, >, <=, >= |
Selection | SelectionOptions | is null, is not null, =, != |
User | UserOptions | is null, is not null, =, != |
Selection List | SelectionOptions (with max_entries > 1) | is null, is not null, in, not in |
User List | UserOptions (with max_entries > 1) | is null, is not null, in, not in |
Search examples
1. Search based on the presence of a label or field
You can search for items where a specific label has (or has not) been applied:
'labels/contract' in labels
not 'labels/contract' in labels
You can also search for items where a specific field has (or has not) been set:
labels/contract.comment IS NOT NULL
labels/contract.comment IS NULL
2. Search based on single-valued fields
You can write search queries to match expected field values. The following table shows the valid field queries:
What you want to query | Query string |
---|---|
Items where comment is set to "hello" | labels/contract.comment = 'hello' |
Files where comment starts with "hello" | labels/contract.comment STARTS WITH 'hello' |
Files where status is executed | labels/contract.status = 'executed' |
Files where status is not executed | labels/contract.status != 'executed' |
Files where execution_date is before a specific date | labels/contract.execution_date < '2020-06-22' |
Files where value_usd (integer) is less than a specific value | labels/contract.value_usd < 2000 |
Files where client_contact is set to a specific email address | labels/contract.client_contact = 'alex@altostrat.com' |
3. Search based on fields with multivalued fields (such as ListOptions.max_entries > 1)
Fields that support multiple values can only be queried using the IN operator:
'EMAIL_ADDRESS' IN labels/project.project_leads
NOT 'EMAIL_ADDRESS' IN labels/project.project_leads
Example
The following code sample shows how to use one or more labelId
to list all
files with a specific label or field value from a Drive file
resource. It also uses the
files.list
method. The request body must
be empty.
If you want to include labelInfo
in the response, you also must specify:
includeLabels
as a comma-separated list of IDs.labelInfo
in thefields
parameter to denote that you want thelabelInfo
returned withinincludeLabels
.
If successful, the response body contains the list of files.
Java
List<File> fileList = driveService.files().list().setIncludeLabels("LABEL_1_ID,LABEL_2_ID").setFields("items(labelInfo, id)").setQ("'labels/LABEL_1_ID' in labels and 'labels/LABEL_2_ID' in labels").execute().getItems();
Python
file_list = drive_service.files().list(includeLabels="LABEL_1_ID,LABEL_2_ID", q="'labels/LABEL_1_ID' in labels and 'labels/LABEL_2_ID' in labels", fields="items(labelInfo, id)").execute();
Node.js
/**
* Search for Drive files with specific labels
* @return{obj} file list with labelInfo
**/
async function searchForFileWithLabels() {
// Get credentials and build service
// TODO (developer) - Use appropriate auth mechanism for your app
const {GoogleAuth} = require('google-auth-library');
const {google} = require('googleapis');
const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
const service = google.drive({version: 'v3', auth});
try {
const fileList = await service.files.list({
includeLabels: 'LABEL_1_ID,LABEL_2_ID',
q: '\'labels/LABEL_1_ID\' in labels and \'labels/LABEL_2_ID\' in labels',
fields:'files(labelInfo, id)',
});
return file;
} catch (err) {
// TODO (developer) - Handle error
throw err;
}
Replace the following:
- LABEL_1_ID: The first
labelId
of a label to return. - LABEL_2_ID: The second
labelId
of a label to return.