Search Engines

Guida provides two distinct search integrations. For local, workspace-scoped indexing with zero setup, you can use the built-in Lucene.NET index. For massive scale and external integration, you can connect directly to Elasticsearch clusters.

---

Local Search Index (Lucene)

g.search.* provides a workspace-scoped full-text search index backed by Lucene.NET. It requires no configuration, runs entirely locally, and persists data inside your workspace folder (.guida/search-index/).

Use cases:

• Indexing extracted text from hundreds of pages for fast retrieval.
• Building local knowledge bases for LLM Retrieval-Augmented Generation (RAG).
• Finding specific queued items or stored documents via fuzzy matching.

Example

async function main() {
  // Index a document
  g.search.index({
    _key: "article-123",
    _collection: "articles",
    title: "Understanding Browser Automation",
    body: "Guida is an agentic browser...",
    url: "https://example.com/article"
  });

  // Query with standard Lucene syntax
  // Supports wildcards, fuzzy matching (~), and field-specific queries
  const results = g.search.query("title:Browser* OR body:automation~");

  g.log(`Found ${results.length} matches:`);
  for (const r of results) {
    g.log(`- ${r.fields.title} (Score: ${r.score})`);
  }
}

6 methods total — see the API Reference for the full list.

---

Elasticsearch

g.elasticsearch.* connects to Elasticsearch clusters for high-throughput ingestion, index management, and raw Query DSL searches.

Unlike the local Lucene index, Elasticsearch requires an external cluster (running locally, via Docker, or on Elastic Cloud).

Connection string format (JSON):

Connections are configured securely in the Secrets pane via the “Add Elasticsearch” dialog. Under the hood, this stores a JSON configuration:

{
  "url": "http://localhost:9200",
  "username": "elastic",
  "password": "password"
}

Use cases:

• Scrape massive datasets and ingest them using high-throughput bulk operations.
• Create and manage indices programmatically.
• Search large datasets using raw Elasticsearch Query DSL.

Example

async function main() {
  const conn = "my-elastic"; // Name of your connection secret

  // Check connection
  const isUp = await g.elasticsearch.ping(conn);
  if (!isUp) return g.log("Connection failed");

  // Bulk index documents with automatic chunking
  const docs = [{ id: 1, title: "Laptop" }, { id: 2, title: "Mouse" }];
  const bulkRes = await g.elasticsearch.bulk(conn, "products", docs, 1000);
  g.log(`Indexed ${bulkRes.successful} out of ${bulkRes.total}`);

  // Query DSL search
  const searchRes = await g.elasticsearch.search(conn, "products", {
    query: { match_all: {} }
  });
  g.log(`Total hits: ${searchRes.hits.total.value}`);
}

8 methods total — see the API Reference for the full list.

---

Security

Connections to external Elasticsearch clusters follow the same security model as secrets:

• MCP-origin scripts are blocked. When an AI agent runs a script via MCP, all g.elasticsearch.* calls return an error. This prevents the AI from accessing external databases through scripted automation. (Note: The local g.search.* Lucene index is accessible to MCP).
• Workers inherit their launcher’s origin. If MCP starts a worker pool, those workers are also blocked from external Elasticsearch access.
• User-initiated scripts have full access. Scripts run via F5, event triggers, and queue processors can use all methods.

Connection credentials are never exposed via MCP tools — the AI only sees the secret name, not the username or passwords.

Next Steps

• API Reference — full method signatures for g.search.* and g.elasticsearch.*.
• Database Integrations — connect to MongoDB, PostgreSQL, and S3-compatible storage.
• Secrets — managing encrypted connection credentials.