result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="What is our refund policy, and how should I explain it to this user?",

    # What to query: "knowledge", "memory", or "all".
    type="all",

    # How to match: "hybrid" (default) or "text" (BM25).
    query_by="hybrid",

    # "thinking" improves quality; use "fast" for lowest latency.
    mode="thinking",

    # Ranking and response controls.
    max_results=10,
    alpha="auto",
    recency_bias=0.2,
    graph_context=True,

    # Pull author-declared related sources into additional_context.
    # Only applies when mode="thinking".
    query_forceful_relations=True,

    # Top-level keys match metadata; additional_metadata is per-source.
    metadata_filters={
        "department": "support",
        "additional_metadata": {
            "source": "policy",
        },
    },

    # Short factual hint; not a hard filter.
    additional_context="User is asking from the billing help center.",
)

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "What is our refund policy, and how should I explain it to this user?",

  // What to query: "knowledge", "memory", or "all".
  type: "all",

  // How to match: "hybrid" (default) or "text" (BM25).
  queryBy: "hybrid",

  // "thinking" improves quality; use "fast" for lowest latency.
  mode: "thinking",

  // Ranking and response controls.
  maxResults: 10,
  alpha: "auto",
  recencyBias: 0.2,
  graphContext: true,

  // Pull author-declared related sources into additional_context.
  // Only applies when mode: "thinking".
  queryForcefulRelations: true,

  // Top-level keys match metadata; additional_metadata is per-source.
  metadataFilters: {
    department: "support",
    additional_metadata: {
      source: "policy",
    },
  },

  // Short factual hint; not a hard filter.
  additionalContext: "User is asking from the billing help center.",
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "What is our refund policy, and how should I explain it to this user?",
    "type": "all",
    "query_by": "hybrid",
    "mode": "thinking",
    "max_results": 10,
    "alpha": "auto",
    "recency_bias": 0.2,
    "graph_context": true,
    "query_forceful_relations": true,
    "metadata_filters": {
      "department": "support",
      "additional_metadata": {
        "source": "policy"
      }
    },
    "additional_context": "User is asking from the billing help center."
  }'

{
  "success": true,
  "data": {
    "chunks": [
      {
        "chunk_uuid": "policy_main_chunk_3",
        "id": "policy_main",
        "chunk_content": "Refunds are issued within 30 days...",
        "source_type": "pdf",
        "source_title": "Compliance Policy",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z",
        "layout": "{\"offsets\":{\"document_level_start_index\":1024},\"page\":3}",
        "relevancy_score": 0.91,
        "extra_context_ids": ["pref-tone"],
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" }
      }
    ],
    "sources": [
      {
        "id": "policy_main",
        "title": "Compliance Policy",
        "type": "pdf",
        "description": "",
        "url": "",
        "timestamp": "2026-05-12T08:14:00Z",
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" },
        "app_kind": null,
        "app_provider": null,
        "app_external_id": null
      }
    ],
    "graph_context": {
      "query_paths": [
        {
          "triplets": [
            {
              "source": {
                "name": "Compliance Policy",
                "type": "DOCUMENT",
                "namespace": "default",
                "entity_id": "entity_compliance_policy",
                "identifier": "https://api.hydradb.com/docs/compliance_policy"
              },
              "relation": {
                "canonical_predicate": "GOVERNS",
                "raw_predicate": "governs and regulates",
                "context": "The compliance policy governs the refund processing timeline of 30 days.",
                "confidence": 0.95,
                "temporal_details": null,
                "timestamp": 1778573640.0,
                "relationship_id": "rel_governs_refunds",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_compliance_policy",
                "target_entity_id": "entity_refund_processing"
              },
              "target": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              }
            }
          ],
          "relevancy_score": 0.89,
          "combined_context": "The Compliance Policy governs the Refund Processing, which regulates refunds.",
          "group_id": null,
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_relations": [
        {
          "triplets": [
            {
              "source": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              },
              "relation": {
                "canonical_predicate": "MANAGED_BY",
                "raw_predicate": "is managed by",
                "context": "Refund processing is managed by the Finance Department.",
                "confidence": 0.9,
                "temporal_details": "Q2 2026 onwards",
                "timestamp": 1778573640.0,
                "relationship_id": "rel_managed_by_finance",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_refund_processing",
                "target_entity_id": "entity_finance_dept"
              },
              "target": {
                "name": "Finance Department",
                "type": "ORGANIZATION",
                "namespace": "default",
                "entity_id": "entity_finance_dept",
                "identifier": "[email protected]"
              }
            }
          ],
          "relevancy_score": 0.82,
          "combined_context": "Refund Processing is managed by the Finance Department.",
          "group_id": "p_0",
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_id_to_group_ids": {
        "policy_main_chunk_3": ["p_0"]
      }
    },
    "additional_context": {
      "pref-tone": {
        "chunk_uuid": "pref-tone",
        "id": "mem_user_alex_tone",
        "chunk_content": "Prefers concise answers.",
        "source_type": "memory",
        "source_title": "User preferences",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z"
      }
    }
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "chunks": [],
    "sources": [],
    "graph_context": {
      "query_paths": [],
      "chunk_relations": [],
      "chunk_id_to_group_ids": {}
    },
    "additional_context": {}
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "query must not be empty"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}