> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/getting-started/fundamentals/explore/file-search.md).

# File Search

**Overview**

**File Search** helps customers understand the sensitive data risk across files in their cloud office environment. When enabled, Material's File Search syncs file activity, classifies sensitive data, and helps customers identify risky sharing patterns. Material provides out-of-the-box remediation tools for addressing these risks across your most sensitive files.

### File Search for Google Drive <a href="#h-file-search-for-google-drive" id="h-file-search-for-google-drive"></a>

Customers with at least one enrolled Google tenant can configure Material to connect to their Google Drive environment. Material supports syncing and sensitive content analysis across both My Drives and Shared Drives, and exposes findings via File Search.

Once enabled, Material File Search starts indexing and analyzing your Google Drive environment. We bias toward processing the most recent business activity, and work backward to build out visibility across the history of your Google Drive environment. Material File Search will sync **6 months of historical activity starting from when you enable syncing**, in addition to **all new activity while the feature is enabled**.

Syncing times vary based on the size and complexity of your Google Drive. But because we start syncing the most recent activity first, most customers can start exploring interesting results within an hour of enabling sync.

***Note:** File Search is currently only supported for Google Drive environments. We are working on similar functionality for Microsoft 365. If you are interested in providing feedback for our Microsoft offering, please reach out to your customer success team.*

### Setup & Configuration <a href="#h-setup-configuration" id="h-setup-configuration"></a>

Customers can configure File Search manually, or by using the in-product set up guide the first time they visit File Search. Setting up File Search for Google Drive follows three basic steps:

* Granting Scopes
* Enabling My Drive Syncing
* Enabling Shared Drive Syncing

#### Granting Scopes <a href="#h-granting-scopes" id="h-granting-scopes"></a>

File Search requires (2) additional Google Drive scopes to be granted to Material via domain-wide delegation:

* `https://www.googleapis.com/auth/drive`
* `https://www.googleapis.com/auth/drive.activity`

Scopes can be granted via [Google Admin](https://admin.google.com/), and must be granted for each Google tenant you would like Material to sync & analyze.

If you have questions about granting scopes, please contact your Material support team.

#### Enabling My Drive Syncing <a href="#h-enabling-my-drive-syncing" id="h-enabling-my-drive-syncing"></a>

Enabling My Drive Syncing allows Material to sync & analyze files stored in My Drives. If you would like to enable My Drive syncing by default for accounts in your organization, visit:

* **Settings > Default Account Settings** and toggle **ON** *Google Drive My Drive Syncing*.

If you have a specific subset of accounts or groups you would like to enable this feature for, use the corresponding Accounts or Groups page to select your target audience. Then select:

* **Edit Settings > Google My Drive Syncing > Set custom Google Drive My Drive Syncing**, and toggle the option **ON**.
* Press **SAVE** to save changes.

#### Enabling Shared Drive Syncing <a href="#h-enabling-shared-drive-syncing" id="h-enabling-shared-drive-syncing"></a>

Enabling Shared Drive Syncing allows Material to sync & analyze files stored in Shared Drives. Because there is no single “owner” of a Shared Drive, Shared Drive Syncing is not tied to a particular Account or Group. Instead, you can enable syncing for all Shared Drives in a tenant, with an option to exclude specific Shared Drives.

Before enabling Shared Drive Syncing, determine if you would like to exclude any Shared Drives from File Search. Reach out to your Material success team to configure exclusions. To verify that Shared Drive exclusions are active, visit:

* **Settings > File Syncing** and review the list of excluded Shared Drives.

To enable Shared Drive Syncing, visit:

* **Settings > File Syncing** and toggle **ON** *Google Drive Shared Drive Syncing*.

If you choose to exclude a Shared Drive at a future date, Material will ignore any new activity from the excluded Shared Drive.

***Note:** Material will **not** automatically delete activity or analysis that has already been processed for a Shared Drive that is later excluded. Data that has already been synced will continue to be visible and searchable in File Search.*

### File Search <a href="#h-file-search" id="h-file-search"></a>

Once Google Drive data is syncing, customers can use File Search to write custom queries about their Google Drive environment. Material offers several *Suggested Queries* to help get you started. Clicking a *Suggested Query* will automatically populate the search bar, and execute the search.

#### Search modes

File Search has three modes, which you choose with **Search Mode** at the top of the search:

* **Quick**: a form where you search by file name, owner, type, location, sharing, and sensitive-data category, without writing a query.
* **Prompt**: describe what you're looking for in plain English, without writing a query.
* **Query**: the full search syntax described below.

<figure><img src="https://3411262179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FksjM8NywYRSHu1IlfxdP%2Fuploads%2FBwR6MdtNfhey9oPYjaSz%2Fimage.png?alt=media&#x26;token=40b08970-7691-41cd-b11e-13492d92d868" alt="File Search Search Mode selector with Quick, Prompt, and Query modes"><figcaption><p>Explorer > Files</p></figcaption></figure>

{% hint style="info" %}
**Prompt** mode isn't available if you've opted out of Material's GenAI capabilities.
{% endhint %}

In **Quick** mode, the **Trusted external** filter matches files shared externally to a trusted entity, separately from files shared externally in general. In **Query** mode, use the `shared.with_trusted_entity` operator.

<figure><img src="https://3411262179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FksjM8NywYRSHu1IlfxdP%2Fuploads%2FFXorR9kO0jrt6QdJtAxY%2Fimage.png?alt=media&#x26;token=8a1b675c-4092-44cd-9231-43115f089aa2" alt="Explorer Files search showing the Trusted external filter"><figcaption><p>Explorer > Files</p></figcaption></figure>

#### Search Syntax <a href="#h-search-syntax" id="h-search-syntax"></a>

File Search is a modern search experience that includes syntax suggestions, inline documentation, type-ahead filtering, and query validation to help you easily write powerful queries.

File Search offers (4) core *namespaces* to help organize your query building blocks. Each namespace has a set of corresponding *properties*:

| Namespace | Description                                                    | Examples                                              |
| --------- | -------------------------------------------------------------- | ----------------------------------------------------- |
| File      | Search across file metadata and content.                       | id, name, type, content, and owner                    |
| Category  | Search for files containing specific sensitive data categories | ssn, credit\_card, ein, passport                      |
| Shared    | Search for files that have been shared in specific ways        | externally, with\_personal\_email, with\_public\_link |
| Location  | Search for files stored in a specific location                 | my\_drive, shared\_drive                              |

When writing a query, all supported namespaces, properties, and operators are suggested to you. In addition, File Search supports `and`, `or`, `not` operators, as well as parentheses `(`, `)`.

#### Validation <a href="#h-validation" id="h-validation"></a>

As you build your query, the Search button will only be enabled when the query syntax is valid.

#### Keyboard Shortcuts <a href="#h-keyboard-shortcuts" id="h-keyboard-shortcuts"></a>

You can use your keyboard to quickly build queries. When the suggestion menu is open, you can use the `DOWN` / `UP` arrow keys to cycle through available options. Pressing `ENTER` or `TAB` will add the currently selected value to your query.

You can dismiss the suggestion menu at any time using ESCAPE. You can reactivate the suggestion menu by pressing `DOWN`.

You can press ENTER anytime the Search button is enabled to execute the current search query.

#### Example Queries <a href="#h-example-queries" id="h-example-queries"></a>

Here are a few example queries to help you understand how the search syntax works:

**Example: Searching for Sensitive Financial Data, Shared Externally**

`shared.externally and (category.bank_routing or category.ein or category.financial_report)`

**Example: Searching for All Sensitive Files an Account Has Access To**

`shared.has_access:"tom@example.com" and category.any`

**Example: Searching in Shared Drives for Files Containing SSNs that are Shared with Personal Email**

`location.is_shared_drive and category.ssn and shared.with_personal_email`

For a full list of available search operators, see the *File Search Operator Reference* below:

#### File Search Operator Reference <a href="#h-file-search-operator-reference" id="h-file-search-operator-reference"></a>

<table><thead><tr><th width="250">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>category</strong></td><td>object</td><td>Search for files based on the kind of sensitive data they contain</td></tr><tr><td><strong>category.any</strong></td><td>bool</td><td>Files containing any category of sensitive data</td></tr><tr><td><strong>category.bank_routing</strong></td><td>bool</td><td>Files containing: US bank routing numbers</td></tr><tr><td><strong>category.confidential</strong></td><td>bool</td><td>Files containing: Information marked as privileged or confidential</td></tr><tr><td><strong>category.credit_card</strong></td><td>bool</td><td>Files containing: Credit card numbers</td></tr><tr><td><strong>category.drivers_license</strong></td><td>bool</td><td>Files containing: Drivers license numbers</td></tr><tr><td><strong>category.ein</strong></td><td>bool</td><td>Files containing: US employer identification numbers</td></tr><tr><td><strong>category.financial_report</strong></td><td>bool</td><td>Files containing: Financial reports such as income statements, balance sheets or projections</td></tr><tr><td><strong>category.health_record</strong></td><td>bool</td><td>Files containing: Health records including lab test results and biometric data</td></tr><tr><td><strong>category.iban</strong></td><td>bool</td><td>Files containing: International Bank Account Number (IBAN) codes</td></tr><tr><td><strong>category.passport</strong></td><td>bool</td><td>Files containing: Passport numbers</td></tr><tr><td><strong>category.password</strong></td><td>bool</td><td>Files containing: Passwords</td></tr><tr><td><strong>category.patent</strong></td><td>bool</td><td>Files containing: Patent documents such as applications and inventor declarations</td></tr><tr><td><strong>category.payroll</strong></td><td>bool</td><td>Files containing: Wages and payroll statements</td></tr><tr><td><strong>category.source_code</strong></td><td>bool</td><td>Files containing: Source code</td></tr><tr><td><strong>category.ssn</strong></td><td>bool</td><td>Files containing: US Social Security numbers</td></tr><tr><td><strong>category.swift</strong></td><td>bool</td><td>Files containing: SWIFT codes</td></tr><tr><td><strong>category.tax_document</strong></td><td>bool</td><td>Files containing: Completed common US Tax Forms such as Form W-2, Form W-9, etc.</td></tr><tr><td><strong>file</strong></td><td>object</td><td>Search for files based on content, owner, and other metadata</td></tr><tr><td><strong>file.content</strong></td><td>string</td><td>Search for files by content</td></tr><tr><td><strong>file.created</strong></td><td>date</td><td>Search for files by created date</td></tr><tr><td><strong>file.id</strong></td><td>string</td><td>Search for files by id</td></tr><tr><td><strong>file.labels</strong></td><td>array</td><td>Search for files with a label</td></tr><tr><td><strong>file.last_modified</strong></td><td>date</td><td>Search for files by last modified date</td></tr><tr><td><strong>file.name</strong></td><td>string</td><td>Search for files by name</td></tr><tr><td><strong>file.owner</strong></td><td>string</td><td>Search for files by owner</td></tr><tr><td><strong>file.type</strong></td><td>object</td><td>Search for files by type</td></tr><tr><td><strong>file.type.document</strong></td><td>bool</td><td>Matches documents (e.g. Google Document, Word Document)</td></tr><tr><td><strong>file.type.drawing</strong></td><td>bool</td><td>Matches drawings (e.g. Google Drawing)</td></tr><tr><td><strong>file.type.image</strong></td><td>bool</td><td>Matches images (e.g. .jpg, .png, .svg, .webp)</td></tr><tr><td><strong>file.type.mime_type</strong></td><td>string</td><td>Search for files matching a mime type string</td></tr><tr><td><strong>file.type.pdf</strong></td><td>bool</td><td>Matches PDFs</td></tr><tr><td><strong>file.type.presentation</strong></td><td>bool</td><td>Matches presentations (e.g. Google Presentation, PowerPoint)</td></tr><tr><td><strong>file.type.spreadsheet</strong></td><td>bool</td><td>Matches spreadshseets (e.g. Google Sheet, Excel)</td></tr><tr><td><strong>file.type.text</strong></td><td>bool</td><td>Matches text files (e.g. .txt, .rtf)</td></tr><tr><td><strong>location</strong></td><td>object</td><td>Search for files based on where they're stored</td></tr><tr><td><strong>location.is_my_drive</strong></td><td>bool</td><td>Search for files that are stored in a user's My Drive</td></tr><tr><td><strong>location.is_shared_drive</strong></td><td>bool</td><td>Search for files that are stored in shared drives</td></tr><tr><td><strong>location.shared_drive</strong></td><td>object</td><td>Search for files that are stored in a specific shared drive</td></tr><tr><td><strong>location.shared_drive.id</strong></td><td>string</td><td>Search for shared drives by id</td></tr><tr><td><strong>shared</strong></td><td>object</td><td>Search for files based on how they've been shared</td></tr><tr><td><strong>shared.externally</strong></td><td>bool</td><td>Search for files that are shared outside the organization in any way (by link or with explicit entities)</td></tr><tr><td><strong>shared.with_trusted_entity</strong></td><td>bool</td><td>Search for files that are shared externally to a trusted entity</td></tr><tr><td><strong>shared.has_access</strong></td><td>string</td><td>Search for files that this email has access to</td></tr><tr><td><strong>shared.restricted</strong></td><td>bool</td><td>Search for files where the general access is restricted to those entities with which the file is explicitly shared</td></tr><tr><td><strong>shared.with</strong></td><td>object</td><td>Search for files that are shared with...</td></tr><tr><td><strong>shared.with.domain</strong></td><td>string</td><td>Search for files that are shared with this entire Google Workspace domain</td></tr><tr><td><strong>shared.with.email</strong></td><td>string</td><td>Search for files that are shared with this email</td></tr><tr><td><strong>shared.with.group</strong></td><td>string</td><td>Search for files that are shared with this group</td></tr><tr><td><strong>shared.with_disposable_email</strong></td><td>bool</td><td>Search for files that are shared with an email address known to be provided by a disposable email service such as Temp-Mail or 10MinuteMail</td></tr><tr><td><strong>shared.with_employee_personal_email</strong></td><td>bool</td><td>Search for files that are shared with a personal email address whose display name or username contains the first or last name of an internal user who has explicit access to the file. Note this does not detect access to the file via group or organization membership.</td></tr><tr><td><strong>shared.with_org</strong></td><td>bool</td><td>Search for files that are shared with the organization</td></tr><tr><td><strong>shared.with_personal_email</strong></td><td>bool</td><td>Search for files that are shared with an email address with a domain typically used for personal email accounts (e.g. gmail.com, yahoo.com)</td></tr><tr><td><strong>shared.with_public_link</strong></td><td>bool</td><td>Search for files that are publicly accessible to anyone with a link</td></tr><tr><td><strong>shared.with_sanctioned_country_tld</strong></td><td>bool</td><td>Search for files shared with top-level domains associated with a country with comprehensive US sanctions (<a href="#top-level-domain-tld-list-for-shared.with_sanctioned_country_tld">complete list here</a>)</td></tr></tbody></table>

### FAQ <a href="#h-faq" id="h-faq"></a>

**What file types are supported?**

File Search supports the most common cloud office documents, including native Google file types *{Google Docs, Google Sheets, Google Slides}*, Microsoft Office documents, and common file types like PDF, CSV, and various images. We are extending file type support all the time. In general, we do not process video files or large binary files.

**Are there file size limitations?**

File Search looks across your entire Google Drive footprint to help provide visibility. We actively process files up to 10 MB in size for sensitive content, and sync metadata to make all other files searchable.

**How often does Material scan for new sensitive content or sharing?**

Material scans for changes in sensitive content and sharing based on document activity, not on a fixed refresh interval. When a change happens in Google Drive, we process that event and rescan for sensitive content whenever appropriate.

**How far back does Material scan historically?**

Material has access to 6 months of activity data for Google Drive, as limited by Google's APIs. We also sync all new activity for as long as the feature is enabled. Note that this historical sync is based on *activity*, not file age. If a file that was created 10 years ago has been modified in the last 6 months, we scan it. And anytime an older file is touched going forward, we will also scan it. Over time, this allows us to cover the vast majority of your entire Google Drive footprint.

**What types of sensitive data does Material scan for?**

Material scans for (16) built-in Sensitive Content Categories. A full list of current Categories is available as part of the suggestion menu in File Search, under the `category` namespace.

**Can I save queries as part of File Search?**

We do not currently support saved queries.

**Why can’t I see a file preview from the Material Admin UX?**

Material currently supports previewing file types that support text extraction, which means we don't preview images today. We also give plain text previews of files like PDFs. We will be continuing to add additional support for previewing richer file types over time.

**Are Google Workspace domains and DNS domains the same thing?**

They are related but not entirely the same. `shared.with.domain` refers to the concept of a Google Workspace domain that is [configured as a trusted domain](https://knowledge.workspace.google.com/admin/domains/allow-external-sharing-with-only-trusted-domains) in your Google Drive sharing settings. If you want to search for a file shared with any email address ending with a particular DNS domain such as `example.com`, perform a search using the contains operator such as `shared.with.email:~"@example.com"` .

***

## Appendix

### **Top Level Domain (TLD) List** for `shared.with_sanctioned_country_tld`

| Cuba        | .cu |
| ----------- | --- |
| Iran        | .ir |
| North Korea | .kp |
| Russia      | .ru |
| Syria       | .sy |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.material.security/getting-started/fundamentals/explore/file-search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.