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.

Label field types

Google Drive label fields are strongly typed with each type supporting different indexing and search semantics. The following table shows the data types available.

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 = ''

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


This example describes how to list all files with a specific label or field value from a Google Drive file resource.

If you want labelInfo to be included in the response, you also need to specify:

  • includeLabels as a comma-separated list of labelIds.

  • labelInfo in the fields parameter to denote that you want the labelInfo returned on the file response.

This example uses one or more labelIds to query for and return files matching the requested label information. It also uses the files.list method.


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();


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)");


* Search for Drive files with specific labels
* @return{obj} file list with labelInfo
async function getFileWithSpecificLabels() {
  // 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: ''});
  const service ={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;