---
name: search_obsidian_notes
kind: function
lang: py
domain: obsidian
version: "1.0.0"
purity: impure
signature: "search_obsidian_notes(vault_dir: str, query: str, in_body: bool = True, in_frontmatter: bool = True) -> list"
description: "Busca un substring (case-insensitive) en todas las notas .md de un vault de Obsidian, excluyendo .obsidian/ y .trash/. Devuelve por nota las lineas que contienen el query con su numero de linea. Los flags in_body/in_frontmatter acotan donde buscar."
tags: [obsidian, notes, search, grep, vault, frontmatter, filesystem]
uses_functions: ["parse_obsidian_frontmatter_py_obsidian"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["os"]
params:
  - name: vault_dir
    desc: "path a la raiz del vault de Obsidian a buscar"
  - name: query
    desc: "substring a buscar (matcheado de forma case-insensitive); no puede ser vacio"
  - name: in_body
    desc: "buscar en el cuerpo de la nota cuando es True (defecto True)"
  - name: in_frontmatter
    desc: "buscar en el bloque de frontmatter cuando es True (defecto True)"
output: "lista de dicts {path, matches} (uno por nota con coincidencias), ordenada por path; cada match es {line, text} con numero de linea 1-based relativo al archivo completo"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/obsidian/search_obsidian_notes.py"
---

## Ejemplo

```python
from obsidian import search_obsidian_notes

# Buscar "presupuesto" en todo el vault (frontmatter + cuerpo)
hits = search_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", "presupuesto")
for h in hits:
    print(h["path"])
    for m in h["matches"]:
        print(f"  L{m['line']}: {m['text']}")

# Solo en el cuerpo, ignorando el frontmatter
solo_cuerpo = search_obsidian_notes(
    "/home/enmanuel/Obsidian/Finanzas", "TODO", in_frontmatter=False
)
```

## Cuando usarla

Cuando necesites un grep de un solo paso sobre un vault de Obsidian: encontrar en que notas aparece un termino y en que lineas, antes de abrir/editar. Util para auditar tags, localizar referencias o construir un indice de busqueda.

## Gotchas

- **Impura**: lee el filesystem. Lanza `ValueError` si `query` es vacio, `FileNotFoundError` si el vault no existe y `NotADirectoryError` si no es un directorio.
- **Exclusion obligatoria**: `.obsidian/` y `.trash/` se podan del recorrido; su contenido nunca se busca ni aparece en resultados.
- **Coste en vaults grandes**: abre y lee CADA nota `.md` linea a linea. En vaults pesados como `NotasDeObsidian` (~554M) esto recorre todo el contenido en memoria por archivo; puede tardar. Acota el vault o pre-filtra con `list_obsidian_notes` si necesitas rendimiento.
- **Numeros de linea**: son 1-based y relativos al archivo completo (incluyen las lineas del frontmatter `---`), de modo que mapean directamente sobre el archivo en disco aunque se busque solo en cuerpo o solo en frontmatter.
- La delimitacion frontmatter/cuerpo se calcula con `parse_obsidian_frontmatter`; si la nota no tiene frontmatter valido, todo se considera cuerpo.
- Archivos con encoding invalido se leen con `errors="replace"`.