Search for files and folders

Use the files.list method to search for files and folders.

Search for all files and folders on the current user's My Drive

Use the files.list without any parameters to return all files and folders.

Search for specific files or folders on the current user's My Drive

To search for a specific set of files or folders, use the query string q with files.list to filter the files to return.

This example shows the format of a query string:

query_term operator values

Where:

  • query_term is the query term or field to search upon. To view the query terms that can be used to filter shared drives, refer to Search query terms.
  • operator specifies the condition for the query term. To view which operators you can use with each query term, refer to Query operators.
  • values are the specific values you want to use to filter your search results.

For example, the following query string filters the search to just return folders:

q: mimeType = 'application/vnd.google-apps.folder'

The following example shows how to use a client library to filter search results to file names and IDs of JPEG image files. This example uses the mimeType query term to narrow results to files of type image/jpeg. This example also sets spaces to drive to further narrow the search to the drive space. When nextPageToken returns null, there are no more results.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.api.services.drive.model.FileList;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of search files. */
public class SearchFile {

  /**
   * Search for specific set of files.
   *
   * @return search result list.
   * @throws IOException if service account credentials file not found.
   */
  public static List<File> searchFile() throws IOException {
           /*Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
           guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    List<File> files = new ArrayList<File>();

    String pageToken = null;
    do {
      FileList result = service.files().list()
          .setQ("mimeType='image/jpeg'")
          .setSpaces("drive")
          .setFields("nextPageToken, items(id, title)")
          .setPageToken(pageToken)
          .execute();
      for (File file : result.getFiles()) {
        System.out.printf("Found file: %s (%s)\n",
            file.getName(), file.getId());
      }

      files.addAll(result.getFiles());

      pageToken = result.getNextPageToken();
    } while (pageToken != null);

    return files;
  }
}

Python

drive/snippets/drive-v3/file_snippet/search_file.py
from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def search_file():
    """Search file in drive location

    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.
    """
    creds, _ = google.auth.default()

    try:
        # create drive api client
        service = build('drive', 'v3', credentials=creds)
        files = []
        page_token = None
        while True:
            # pylint: disable=maybe-no-member
            response = service.files().list(q="mimeType='image/jpeg'",
                                            spaces='drive',
                                            fields='nextPageToken, '
                                                   'files(id, name)',
                                            pageToken=page_token).execute()
            for file in response.get('files', []):
                # Process change
                print(F'Found file: {file.get("name")}, {file.get("id")}')
            files.extend(response.get('files', []))
            page_token = response.get('nextPageToken', None)
            if page_token is None:
                break

    except HttpError as error:
        print(F'An error occurred: {error}')
        files = None

    return files


if __name__ == '__main__':
    search_file()

Node.js

drive/snippets/drive_v3/file_snippets/search_file.js
/**
 * Search file in drive location
 * @return{obj} data file
 * */
async function searchFile() {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const files = [];
  try {
    const res = await service.files.list({
      q: 'mimeType=\'image/jpeg\'',
      fields: 'nextPageToken, files(id, name)',
      spaces: 'drive',
    });
    Array.prototype.push.apply(files, res.files);
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.php
use Google\Client;
use Google\Service\Drive;
function searchFiles()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $files = array();
        $pageToken = null;
        do {
            $response = $driveService->files->listFiles(array(
                'q' => "mimeType='image/jpeg'",
                'spaces' => 'drive',
                'pageToken' => $pageToken,
                'fields' => 'nextPageToken, files(id, name)',
            ));
            foreach ($response->files as $file) {
                printf("Found file: %s (%s)\n", $file->name, $file->id);
            }
            array_push($files, $response->files);

            $pageToken = $response->pageToken;
        } while ($pageToken != null);
        return $files;
    } catch(Exception $e) {
       echo "Error Message: ".$e;
    }
}

To restrict the search to folders, use the query string to set the MIME type to q: mimeType = 'application/vnd.google-apps.folder'

For further information on MIME types, see Google Workspace and Drive MIME Types.

Query string examples

This table shows some basic query strings. The actual code differs depending on the client library you use for your search.

What you want to query Example
Files with the name "hello" name = 'hello'
Files with a name containing the words "hello" and "goodbye" name contains 'hello' and name contains 'goodbye'
Files with a name that does not contain the word "hello" not name contains 'hello'
Folders that are Google apps or have the folder MIME type mimeType = 'application/vnd.google-apps.folder'
Files that are not folders mimeType != 'application/vnd.google-apps.folder'
Files that contain the text "important" and in the trash fullText contains 'important' and trashed = true
Files that contain the word "hello" fullText contains 'hello'
Files that do not have the word "hello" not fullText contains 'hello'
Files that contain the exact phrase "hello world" fullText contains '"hello world"'
Files with a query that contains the "\" character (e.g., "\authors") fullText contains '\\authors'
Files with ID within a collection, e.g. parents collection '1234567' in parents
Files in an Application data folder in a collection 'appDataFolder' in parents
Files for which user "test@example.org" has write permission 'test@example.org' in writers
Files for which members of the group "group@example.org" have write permission 'group@example.org' in writers
Files modified after a given date modifiedTime > '2012-06-04T12:00:00' // default time zone is UTC
Files shared with the authorized user with "hello" in the name sharedWithMe and name contains 'hello'
Files that have not been shared with anyone or domains (only private, or shared with specific users or groups) visibility = 'limited'
Image or video files modified after a specific date modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')

Search for files with a custom file property

To search for files with a custom file property, use the appProperties search query term with a key and value. For example, to search for a custom file property called additionalID with a value of 8e8aceg2af2ge72e78:

appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }

For further information on custom file properties, see Add custom file properties.

Search for files with a specific label or field value

To search for files with specific labels, use the labels search query term with a specific label ID. For example: 'labels/LABEL_ID' in labels

To search for files without a specific label ID: Not 'labels/LABEL_ID' in labels

You can also search for files based on specific field values. For example, to search for files with a text value: labels/LABEL_ID.text_field_id = 'TEXT'

For more details information, see Search for files with a specific label or field value.

Search the corpora

Searches that call files.list use the user corpus by default. To search other corpora, such as files shared to a Google Workspace domain, use the corpora parameter.

Multiple corpora may be searched in a single query, though incomplete results may be returned if the combined corpus is too large. If incompleteSearch result is true, not all documents have been returned.