Search for files with a specific label or field value

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

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 the fields parameter to denote that you want the labelInfo returned within includeLabels.

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.