---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: fsquery
excerpt: |
  DuckDB Community Extensions
  Query filesystem metadata using SQL with recursive directory traversal

extension:
  name: fsquery
  description: Query filesystem metadata using SQL with recursive directory traversal
  version: 0.1.0
  language: C++
  build: cmake
  license: MIT
  maintainers:
    - halgari
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads"

repo:
  github: halgari/fsquery
  ref: d7a8acb6f3d5f73d1c7738da57ee3da1ce782f18

docs:
  hello_world: |
    -- Scan a directory and find large files
    SELECT path, size, mtime
    FROM fsquery_scan('/home')
    WHERE is_regular_file AND size > 1000000
    ORDER BY size DESC
    LIMIT 10;
  extended_description: |
    The **fsquery** extension adds a `fsquery_scan(path)` table function that recursively
    traverses directories and returns file metadata including path, size, timestamps,
    permissions, and file type flags.

    ### Features
    - **14 metadata columns**: path, mode, size, uid, gid, atime, mtime, ctime, nlink, ino, dev, is_regular_file, is_directory, is_symlink
    - **Filter pushdown**: Path prefix filters are pushed down to avoid scanning irrelevant directories. When using `fsquery_scan()` (no explicit path), filters like `path >= '/home/user/docs'` or `path IN (...)` cause only those subtrees to be traversed.
    - **Projection pushdown**: Only requested columns are computed, skipping unnecessary `stat` field extraction.
    - Cross-platform support (Linux, macOS, Windows)

    ### Examples

    Scan a specific directory:
    ```sql
    SELECT path, size, mtime FROM fsquery_scan('/var/log') WHERE is_regular_file;
    ```

    Filter pushdown — only `/etc` and `/var/log` are traversed, not the entire filesystem:
    ```sql
    SELECT path, size FROM fsquery_scan()
    WHERE path >= '/etc' OR path >= '/var/log';
    ```

    Find recently modified files:
    ```sql
    SELECT path, mtime FROM fsquery_scan('/home')
    WHERE is_regular_file AND mtime > TIMESTAMP '2025-01-01'
    ORDER BY mtime DESC;
    ```

    Find all symlinks:
    ```sql
    SELECT path FROM fsquery_scan('/usr') WHERE is_symlink;
    ```

extension_star_count: 2
extension_star_count_pretty: 2
extension_download_count: 4110
extension_download_count_pretty: 4.1k
image: '/images/community_extensions/social_preview/preview_community_extension_fsquery.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ✅ | ❌ | ❌ | ❌ |
| Linux ARM64 | ❌ | ✅ | ❌ | ❌ | ❌ |
| macOS AMD64 | ❌ | ✅ | ❌ | ❌ | ❌ |
| macOS ARM64 | ❌ | ✅ | ❌ | ❌ | ❌ |
| Windows AMD64 | ❌ | ✅ | ❌ | ❌ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

| function_name | function_type | description | comment | examples |
|---------------|---------------|-------------|---------|----------|
| fsquery_scan  | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.