Orama Cloud Not Working

[rayliverified]

Hello and thank you for building Orama! Unfortunately, I'm having some difficulties with Orama Cloud.

There are two core issues:

1. Orama Cloud AI search doesn't work, it's currently broken.
2. Orama Cloud's new core library does not integrate with Orama UI, and there is a lot of confusion with the self hosted and Orama UI components.

AI search gets stuck and fails here:

AI Summary of the issue below:

The Four Libraries

1. @orama/orama — Local / Self-Hosted Search

The original open-source engine. Runs fully in-memory in the browser or Node. No cloud, no API keys.

import { create, insertMultiple, search } from '@orama/orama';

const db = await create({ schema: { title: 'string', text: 'string' } });
await insertMultiple(db, documents);
const results = await search(db, { term: 'query' });

• Data lives: locally in memory (loaded from a JSON file, a local server, etc.)
• Auth: none
• Works with wc-components: ✅ element.clientInstance = db (type: AnyOrama)

---

2. @oramacloud/client — Old Cloud SDK

The original hosted-cloud SDK. Connects to a deployed Orama index via a per-project endpoint URL that you copy from the Orama Cloud dashboard.

import { OramaClient } from '@oramacloud/client';

const client = new OramaClient({
  endpoint: 'https://cloud.orama.run/v1/indexes/<index-id>',
  api_key: 'your-readonly-api-key',
});
const results = await client.search({ term: 'query' });

• Data lives: Orama Cloud (hosted)
• Auth: api_key + endpoint (endpoint is a full URL from the dashboard)
• Works with wc-components: ✅ element.clientInstance = client (type: OramaClient)
• Endpoint source: Orama Cloud dashboard → your index → "Connect" tab → cloud.orama.run/v1/indexes/<id>

---

3. @orama/core — New Cloud SDK

The modern replacement for @oramacloud/client. Purely projectId-based — no endpoint URL needed. Orama resolves the endpoint internally.

import { OramaCloud } from '@orama/core';

const orama = new OramaCloud({
  projectId: '17a4d07f-729f-429d-9a2d-8a28a6ec3ebb',
  apiKey: 'c1_9-IgUp2...',
});

// Search
const results = await orama.collections.search({ term: 'query' });

// AI Chat
const session = await orama.ai.createAISession();
for await (const chunk of session.answerStream({ query: 'question' })) {
  console.log(chunk);
}

• Data lives: Orama Cloud (hosted)
• Auth: projectId + apiKey only
• Works with wc-components: ⚠️ Partial — see compatibility table below

---

4. @orama/wc-components — UI Components

Web components (<orama-search-box>, <orama-chat-box>) designed to plug into any of the above. The bridge between UI and search engine.

<orama-search-box></orama-search-box>

import { defineCustomElements } from '@orama/wc-components/loader';
await defineCustomElements(window);

const box = document.querySelector('orama-search-box');
box.clientInstance = myOramaDbOrClient;

---

Compatibility Matrix

SDK / Instance	Prop to use	Works?	Notes
@orama/orama db	clientInstance	✅ Yes	Fully documented, local
@oramacloud/client OramaClient	clientInstance	✅ Yes	Needs endpoint URL from dashboard
CloudIndexConfig { api_key, endpoint }	index	✅ Yes	Component creates OramaClient internally
@orama/core OramaCloud	oramaCoreClientInstance	⚠️ Unclear	Expects CollectionManager, not OramaCloud
@orama/core CollectionManager	oramaCoreClientInstance	❓ Untested	Would need CollectionManager directly

Why OramaCloud ≠ CollectionManager

oramaCoreClientInstance is typed as CollectionManager. OramaCloud internally delegates to a CollectionManager, but it is not a CollectionManager and does not expose .client publicly:

// @orama/core — cloud.d.ts
export declare class OramaCloud {
  ai: CollectionManager['ai'];
  collections: CollectionManager['collections'];
  index: CollectionManager['index'];
  // ...delegates everything to an internal CollectionManager
  // but does NOT expose .client as a public property
  constructor(config: ProjectManagerConfig);
}

There is no documented way to extract the inner CollectionManager from an OramaCloud instance and pass it to oramaCoreClientInstance.

---

• The UI does support Orama Cloud via the old SDK (@oramacloud/client + endpoint URL). This is the well-documented path.
• The UI partially supports the new SDK (@orama/core) via the oramaCoreClientInstance prop, but the integration between OramaCloud and CollectionManager is not publicly documented or cleanly exposed.
• The new SDK's AI chat (orama.ai.createAISession()) works independently from the UI components and does not need any endpoint.

Additional Orama Cloud Issues and AI Debugging:

---

Title: @orama/core + @orama/wc-components: integration gaps, undocumented oramaCoreClientInstance, hanging BeforeRetrieval hook, and search UX issues

---

Introduction

We've been using @orama/core (the new cloud SDK) alongside @orama/wc-components to build a search UI backed by Orama Cloud. During this process we discovered several gaps between the libraries — some are documentation issues, some are API mismatches, and some are cloud-side bugs. Filing them together since they compound each other.

The @orama/core path is where things break down.

---

Issues

1 — oramaCoreClientInstance prop is undocumented

<orama-search-box> exposes two props for connecting a client:

clientInstance?: OramaClient | AnyOrama;      // documented
oramaCoreClientInstance?: CollectionManager;  // not documented anywhere

There is no mention of oramaCoreClientInstance in the docs, README, or Storybook. Developers using @orama/core have no way to discover this prop exists.

---

2 — OramaCloud is not a CollectionManager — no clean path to wire it up

oramaCoreClientInstance expects a CollectionManager. OramaCloud from @orama/core delegates the CollectionManager interface but is not a subclass of it and does not expose its inner CollectionManager publicly:

// @orama/core — cloud.d.ts
export declare class OramaCloud {
  ai: CollectionManager['ai'];
  collections: CollectionManager['collections'];
  // delegates everything — but IS NOT a CollectionManager
  // .client (inner CollectionManager) is not a public property
}

Passing oramaCloud to oramaCoreClientInstance works via JavaScript duck-typing at runtime but fails TypeScript type-checking and is completely undocumented.

Workaround used: Cast and assign — element.oramaCoreClientInstance = oramaCloud as any.

---

3 — ChatService calls client.createAnswerSession() which doesn't exist on @orama/core

When oramaCloud is connected via oramaCoreClientInstance, ChatService internally calls:

this.answerSession = this.client.createAnswerSession({ events: { onStateChange } });

This method comes from @oramacloud/client's OramaClient. OramaCloud from @orama/core has no such method — the equivalent is oramaCloud.ai.createAISession(). The result is:

TypeError: this.client.createAnswerSession is not a function

There is even a TODO comment in ChatService.js acknowledging this:

/* TODO: Interfaces between Orama Core and Orama Cloud are different.
  we must cast the client to the correct type and use different implementations.
  We are not doing that for the sake of speed, but we must circle back to this.
*/

Workaround used: Polyfill createAnswerSession directly on the oramaCloud instance to bridge it to oramaCloud.ai.createAISession().answerStream().

---

4 — facetProperty causes HTTP 422 from Orama Cloud

Setting element.facetProperty = 'type' on <orama-search-box> causes SearchService to include a where filter when a facet is selected:

where: { type: { eq: "thread" } }

Orama Cloud responds with HTTP 422:

Failed to deserialize the JSON body into the target type:
where: Invalid where filter for key type:
NotWhereFilter(WhereFilter { filter_on_fields: [("eq", String("thread"))], ... })

The error is silently logged as SearchService error with no feedback to the developer about why the field is not filterable.

Workaround used: Remove facetProperty entirely.

---

5 — Long natural language queries highlight stop words in results

When a user types a full sentence (e.g. "Write a SaaS launch tweet for Codelessly") into the search box, every token is matched and highlighted — including single characters like a, to, for, an.

This creates heavy visual noise where one- and two-letter words are highlighted across every result. There is no minimum token length or default stop-word exclusion for highlights.

Suggested fix: Apply a minimum token length to the highlight pass (e.g. 3 chars), ship a default English stop-word list for highlights, or expose a highlightStopWords option on the component.

---

Additional Cloud Issues (Orama Cloud — not SDK)

These were discovered by testing the @orama/core AI session API directly in Node.js.

6 — answerStream hangs indefinitely at execute_before_retrieval_hook

Calling oramaCloud.ai.createAISession().answerStream({ query }) gets permanently stuck at the execute_before_retrieval_hook step. onStateChange fires through the setup steps then stops — no completion, no error:

step=starting
step=initializing
step=handle_gpu_overload  (×2)
step=get_llm_config
step=simple_rag
step=determine_query_strategy
step=execute_before_retrieval_hook  ← hangs forever

Tested with 45-second and 3-minute timeouts in Node.js — the stream never progresses. No error is thrown or surfaced to the caller. The only escape is session.abort().

Expected: Hook failures should surface as a catchable error with a clear message. The SDK should also support a client-configurable timeout on answerStream.

7 — oramaCloud.collections.search() does not exist

The @orama/core types suggest searching via oramaCloud.collections.search() but this method does not exist at runtime. The correct method is oramaCloud.search() directly on the OramaCloud instance. The collections namespace is for collection management (CRUD), not querying.

Expected: Either correct the type structure to make the API surface self-evident, or add a search method to the collections namespace that works as expected.

---