fn_registry/python/functions/metabase/metabase_create_document.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
metabase_create_document	function	py	infra	1.1.0	impure	def metabase_create_document(client: MetabaseClient, name: str, document: dict, collection_id: int = 0, *, validate: bool = True) -> dict	Crea un document con contenido ProseMirror. Valida el arbol contra la whitelist de nodos ANTES de enviar (evita documentos que la API acepta pero el frontend renderiza vacíos). Usar prosemirror_card_embed() para embeber cards.	metabase document create api prosemirror python	metabase_validate_document_payload_py_infra			false	error_go_core	httpx uuid	name desc client instancia autenticada de MetabaseClient name desc name titulo del document (1-254 caracteres, no blank) name desc document arbol ProseMirror JSON: {type: 'doc', content: [...]}, o '' para arrancar vacio name desc collection_id ID de coleccion destino (0 = root) name desc validate si True (default), valida el ProseMirror antes de enviar. Lanza ValueError si hay nodos no soportados	dict: document recien creado con id, entity_id y metadata	false			python/functions/metabase/documents.py

Ejemplo

from metabase.documents import metabase_create_document, prosemirror_card_embed

doc = metabase_create_document(client, "Reporte Q1", {
    "type": "doc",
    "content": [
        {"type": "heading", "attrs": {"level": 1},
         "content": [{"type": "text", "text": "KPIs"}]},
        {"type": "paragraph",
         "content": [{"type": "text", "text": "Revenue por canal:"}]},
        prosemirror_card_embed(42, height=450),
    ]
})

Nodos ProseMirror — whitelist

Renderizan correctamente (TipTap v0.59): doc, paragraph, text, heading, bulletList, orderedList, listItem, blockquote, codeBlock, horizontalRule, hardBreak, cardEmbed, flexContainer, smartLink, resizeNode, mention

La API acepta pero el frontend IGNORA (resultado: documento vacío): callout, taskList, taskItem, details, table, tableRow, tableCell, image, iframe

Marks que renderizan: bold, italic, strike, code, link Marks ignorados: underline, highlight, subscript, textStyle

cardEmbed — SIEMPRE envolver en resizeNode

Un cardEmbed desnudo renderiza pero queda con ~50px de alto. Metabase espera que vaya dentro de un resizeNode:

# MAL — card diminuta
{"type": "cardEmbed", "attrs": {"id": 42}}

# BIEN — usar el helper
from metabase.documents import prosemirror_card_embed
prosemirror_card_embed(42, height=450)
# Genera: {"type": "resizeNode", "attrs": {"height": 450, "minHeight": 280},
#          "content": [{"type": "cardEmbed", "attrs": {"id": 42, ...}}]}

Notas

• La validación (validate=True) llama internamente a metabase_validate_document_payload. Si detecta nodos no soportados, lanza ValueError ANTES de hacer el POST — evita documentos que se ven vacíos.
• Pasar validate=False solo si se está experimentando con nodos nuevos.
• Para destacar texto, usar blockquote (NO callout).
• Cuando embebes un card via cardEmbed, Metabase crea una referencia al card — el card debe existir.