# Search and field selectors

files.list search terms and orderBy, and how fields narrows each route's response.

`files.list` finds files with a `q` search, and `fields` narrows a response to the members you name. Find the images in My Drive and return only their names and types:

```bash
AUTH='Authorization: Bearer ya29.placeholder'
curl -s -G -H "$AUTH" "$RYSTIC_URL/drive/v3/files" --data-urlencode "q=mimeType contains 'image' and trashed = false" --data-urlencode 'fields=files(name,mimeType)' | jq -c .files
# -> [{"mimeType":"image/x-canon-cr2","name":"IMG_0042.CR2"},{"mimeType":"image/jpeg","name":"beach-sunrise.jpg"}]
```

### List a folder's files

```bash
curl -s -G -H "$AUTH" "$RYSTIC_URL/drive/v3/files" --data-urlencode "q='1MVfolder2025Shoots02' in parents" --data-urlencode 'orderBy=name' --data-urlencode 'fields=files(name)' | jq -c '[.files[].name]'
# -> ["beach-sunrise.jpg","IMG_0042.CR2","reel-final.mp4"]
```

### Find a file by its properties

```bash
curl -s -G -H "$AUTH" "$RYSTIC_URL/drive/v3/files" --data-urlencode "q=properties has { key='client' and value='northwind' }" --data-urlencode 'fields=files(name)' | jq -c '[.files[].name]'
# -> ["reel-final.mp4"]
```

### Test a selector the simulator refuses

```bash
curl -s -H "$AUTH" "$RYSTIC_URL/drive/v3/files/1MVmp4ReelFinal04?fields=nope" | jq -c '.error.errors[0] | {reason, location}'
# -> {"reason":"invalidParameter","location":"fields"}
```

### Search terms

`files.list` takes these `q` terms, joined by `and`, `or`, `not` and parentheses:

| Term | What it takes |
|---|---|
| `name` | `=`, `!=` and `contains`, which matches the start of each word in any order |
| `mimeType` | `=`, `!=` and `contains` |
| `fullText contains` | whole words of the name, the description or a text file's content |
| `'<folderId>' in parents` | a folder id or `'root'` for My Drive's top level |
| `trashed`, `starred` | `=` and `!=` |
| `sharedWithMe` | `=`, or the bare term |
| `modifiedTime` | `<` and `>` only |
| `createdTime` | `<`, `<=`, `>` and `>=` |
| `'me' in owners`, `in writers`, `in readers` | `'me'`, an email or a permission id; `writers` and `readers` match a user whose role is at least that one, inherited through folders |
| `properties has`, `appProperties has` | `{key='…' and value='…'}` |

`orderBy` takes every documented key, each with `desc`, and lists the newest `modifiedTime` first without one. Any other term, such as the reversed `parents in 'root'`, returns 400 `invalid`, and so does a time term with an operator the table does not list.

**Differs from Google Drive:** Drive's search guide documents more terms and operators than the simulator takes, such as `viewedByMeTime`, `shortcutDetails.targetId` and `visibility`.

### Field selectors

`fields` narrows a successful response to the members it names, and an error response stays whole. A `files.create` refused for its selector still writes the file, while an upload refused this way writes nothing.

| Selector | Methods | Response |
|---|---|---|
| empty | files, changes, permissions, revisions | `{}` |
| absent or empty | `about.get`, comments and replies | 400 `required` |
| one that does not parse, or names a member the resource lacks at any depth (`nope`, `owners(nope)`, `ID`) | all of the above | 400 `invalidParameter` "Invalid field selection nope" at location `fields` |

The shared drive, operations, export and download routes do not check `fields`, so they accept an empty or unknown selector. On an `alt=media` download, Drive ignores `fields` too, and may on an export (unconfirmed).

**Differs from Google Drive:** Drive may refuse a bad selector on the shared drive, operations and `files.download` routes too (unconfirmed).

On these routes, a valid selector does not always narrow the response:

| Route | What the simulator returns |
|---|---|
| `drives.get` | the top-level members the selector names, each whole: `capabilities(canEdit)` returns every capability (unconfirmed) |
| `drives.list`, `files.download` | whole records, whatever `fields` names |
| creating or updating a drive | `kind`, `id` and `name`, whatever `fields` names |
| hiding or unhiding a drive | `kind`, `id` and `name`, whatever `fields` names (unconfirmed) |
| `operations.get` | the whole operation, whatever `fields` names (unconfirmed) |

**Differs from Google Drive:** Drive narrows `drives.list` and `files.download` to the selector. Without `fields`, Drive's `drives.list` returns only `kind`, `id` and `name` for each drive.

**Differs from Google Drive:** Drive narrows an updated drive to the selector and returns the whole created drive for `*`. It may narrow a created drive to another selector (unconfirmed).

---

Source: https://www.rystic.ai/docs/simulators/google-drive/features/search-and-fields · Markdown: https://www.rystic.ai/docs/simulators/google-drive/features/search-and-fields.md