Why can’t you ask Cassandra for “only movies scoring above 0.85”? Because CQL can’t filter on a similarity score, so that cutoff has to live in your application. This post builds it: a TypeScript API for Apache Cassandra® 5.0 that takes one movie and returns movies like it, with their scores.

This is the eighth instalment in the Cassandra 5.0 series where I’ll show you how to build an AI movie recommender app with Python and TypeScript.

More like this, with scores

Here is where we’re headed. We’ll ask a running API for movies like Her (2013), and it answers with five movies and a score for each:

curl "http://127.0.0.1:8000/movies/Q788822/similar?limit=5&within=1"

The response, with line breaks added so it’s readable:

{
  "seed": { "movie_id": "Q788822", "title": "Her", "release_year": 2013 },
  "results": [
    { "movie_id": "Q107167", "title": "Sleepless in Seattle", "release_year": 1993, "score": 0.8577 },
    { "movie_id": "Q154935", "title": "500 Days of Summer", "release_year": 2009, "score": 0.8572 },
    { "movie_id": "Q16635326", "title": "Ex Machina", "release_year": 2014, "score": 0.8498 },
    { "movie_id": "Q208269", "title": "Eternal Sunshine of the Spotless Mind", "release_year": 2004, "score": 0.8495 },
    { "movie_id": "Q107270", "title": "Lost in Translation", "release_year": 2003, "score": 0.8484 }
  ]
}

The Q788822 is Her’s ID, which we’ll explain shortly. The within setting is the threshold, and by the end of this post you’ll know why it isn’t a plain “minimum score”. Along the way, you’ll see that “more like this” doesn’t need a call to an embedding model at all.

What you’ll learn and what you need

You’ll learn how to:

  • read similarity scores beside an ANN OF query from TypeScript,
  • pass a stored vector from one query into another with the Node.js driver, and
  • apply a score threshold in code, and why a fixed number doesn’t work.

A quick recap, in case you skipped earlier weeks. An embedding is a list of numbers that captures what a text means, and the plot_embedding column holds one for every movie’s plot. ANN OF asks the vector index for the stored embeddings closest to the one you give it, and similarity_cosine returns a score for each result. We covered the index in week 3 and the scores in week 7.

We’ll continue to use the same Astra DB and the movies table from week 3, with every plot embedded and the vector index built.

For full disclosure, I’m an Apache Cassandra committer and a Developer Advocate at DataStax, now an IBM company. We’re using Astra DB for convenience so you can focus on building apps as a developer without worrying about how to install or configure a cluster, but the examples in this post are verified to run on Cassandra 5.0.

You also need the repo and the .env file with your Astra DB token from the series setup page, and Node.js 20.11 or later. The code uses import.meta.dirname and Node’s built-in --env-file option, which need that version. I ran it on Node 26. You don’t need a Google AI Studio key this week, because nothing here calls Gemini. If your database has been idle for a while, check that it isn’t hibernated first. Section 2.4 of the setup page shows how.

Set up the TypeScript project

The TypeScript code lives in app-ts/, beside the Python app/ from weeks 2, 4 and 6. It’s a separate folder because the two apps share a database but nothing else: they have different dependencies and different commands. Both read the same .env file and secure connect bundle from the repo’s root.

From the repo’s root directory, install the dependencies:

cd app-ts
npm install

The package.json pins four things we’ll use:

PackageWhat it does
cassandra-driver 4.10.0The Node.js driver, which talks to Astra DB and Cassandra
fastify 5.12.7The web framework for our one endpoint
tsx 4.21.1Runs TypeScript files directly, with no build step
typescript 5.9.3Checks the types, through npm run typecheck

I chose Fastify because the endpoint needs only a route and a few validated query parameters, and it checks them for us from a plain JSON schema. Unlike the FastAPI apps in the Python weeks, it has no built-in /docs page, so we use curl.

Connect to Astra DB from Node

The file app-ts/src/connection.ts creates the driver’s Client. It mirrors the Python tools/connection.py: if ASTRA_DB_TOKEN is set, it connects to Astra DB, and otherwise it connects to a plain Cassandra cluster at CASSANDRA_HOSTS. That is how the same app runs on a cassandra:5.0 container by changing only .env. It’s a separate TypeScript file because Node can’t import a Python one.

The Astra DB branch is the part you’ll use:

return new Client({
  cloud: {
    secureConnectBundle: resolve(import.meta.dirname, "../../secure-connect-cmovies.zip"),
  },
  credentials: { username: "token", password: env.ASTRA_DB_TOKEN },
  keyspace,
});

The secure connect bundle is the zip file from the setup page, and the username is the literal word token, with your application token as the password. The keyspace defaults to default_keyspace, the one where the loader put your tables.

Read a movie’s vector, then use it

“More like this” starts from a movie that’s already in the table, and that’s the reason it needs no embedding call. In week 4 we sent the reader’s phrase to Gemini to get a vector. Here the vector we want, the seed movie’s plot_embedding, is already stored, so we read it from movies and use it as the search vector.

The seed is identified by its movie_id, the Wikidata ID that is the table’s primary key, for example Q788822 for Her. I used IDs rather than titles because a title isn’t unique: a search for “her” in week 2’s title index also returns Death Becomes Her and Talk to Her. To find an ID, run this in the Astra CQL console, after USE default_keyspace;:

SELECT movie_id, title, release_year FROM movies WHERE title_words CONTAINS 'her' LIMIT 20;

Our app runs two statements for each request. The first reads the seed:

const SEED_QUERY =
  "SELECT movie_id, title, release_year, plot_embedding FROM movies WHERE movie_id = ?";

The second asks for the closest movies and their scores:

const SIMILAR_QUERY =
  "SELECT movie_id, title, release_year, similarity_cosine(plot_embedding, ?) AS score " +
  "FROM movies ORDER BY plot_embedding ANN OF ? LIMIT ?";

It’s the query from week 7, with every vector replaced by a ?. We return only similarity_cosine because week 7 showed that on cMovie’s vectors all three functions agree. We run both statements with prepare: true, so the driver prepares each one once and reuses it for every request.

The driver only binds its own vector type

Here is the one surprise in the driver. Binding a plain JavaScript array of 3,072 numbers to ANN OF fails, with this message:

Driver only supports Vector type when encoding a vector

The driver needs to know the value is a vector, not a list, so it can encode it correctly. It decodes a stored vector as a Vector object, so we can pass the seed row’s own plot_embedding straight back in without any conversion:

const result = await client.execute(
  SIMILAR_QUERY,
  [seed.plot_embedding, seed.plot_embedding, limit + 1],
  { prepare: true, consistency: types.consistencies.one },
);

A phrase you embed yourself, as in week 4, would need wrapping with new types.Vector(...). We don’t need that this week.

The consistency option is the Node version of the setting from week 4. A vector query can only run at consistency level ONE, so we ask for it on this statement. Without it, the driver’s default level makes Astra DB print the LOCAL_ONE downgrade warning we met in week 3, and it doesn’t change the results.

The seed is its own best match

Notice that we ask for limit + 1 rows. A movie is more similar to itself than to any other movie, so the seed comes back first with a score of 1, and showing Her as a recommendation for Her isn’t useful. The cure is two lines of code, which we’ll see in the full route. We drop the row whose movie_id equals the seed’s, and ask for one extra row so we still return limit movies afterwards.

The threshold CQL can’t apply

CQL has no way to say “only movies above 0.85”. In week 7 we tried WHERE similarity_cosine(...) > 0.8 and got a SyntaxException, because only a column name can sit on the left of a WHERE condition. So the cutoff belongs in TypeScript, after the rows come back.

The obvious design is a min_score parameter. Let’s see how it behaves. This table counts the other movies in the 999 rows the index returned for Her that reach each score:

Minimum scoreMovies kept
0.852
0.80672
0.75998

A cutoff of 0.85 leaves two movies, and 0.80 leaves 672 of them, which is most of the table. The same happens with Parasite: 2 movies at 0.85 and 693 at 0.80. There is no number in between that gives you a sensible short list. Embedding scores bunch together in a narrow band: for Her, every movie in the table scores between 0.771 and 1.0. That’s a property of this model’s vectors, and I’m not claiming it holds for every embedding model. The practical point is that a number you tune for one seed, or one model, is wrong for the next.

Measure from the best neighbour instead

The fix is a relative threshold. We keep the movies whose score is within a small gap of the best neighbour’s score, and call that gap within. For Her, the best neighbour scores 0.8577, so within=0.01 keeps movies down to 0.8477. The rest of the list follows the same logic whatever the seed:

// CQL can't filter on a score, so the threshold is applied here. It is
// relative to the best neighbour because the scores bunch together.
const best = neighbours[0]?.score ?? 0;
const results = neighbours.filter((n) => n.score >= best - within);

Even a relative threshold gives lists of different sizes. This is the number of movies returned with limit=20:

Seedwithin 0.01within 0.02within 0.03
Her51520
Parasite1720

So within is a knob you tune, not a constant. I default it to 0.02 and recommend you try a few seeds before you settle on a value for your own app. There’s also a limit on what the threshold can do. CQL can’t stop at a score, so we always ask Cassandra for limit + 1 rows and trim in code, and the threshold can only ever make the list shorter.

The endpoint

Here is the whole route, from app-ts/src/server.ts. The schema block is how Fastify validates the query parameters: limit is an integer from 1 to 50 (default 10) and within is a number from 0 to 1 (default 0.02).

app.get<{
  Params: { id: string };
  Querystring: { limit: number; within: number };
}>(
  "/movies/:id/similar",
  {
    schema: {
      querystring: {
        type: "object",
        properties: {
          limit: { type: "integer", minimum: 1, maximum: 50, default: 10 },
          within: { type: "number", minimum: 0, maximum: 1, default: 0.02 },
        },
      },
    },
  },
  async (request, reply) => {
    const { id } = request.params;
    const { limit, within } = request.query;

    const seedResult = await client.execute(SEED_QUERY, [id], { prepare: true });
    const seed = seedResult.first();
    if (!seed) {
      return reply.code(404).send({ error: `No movie with id ${id}` });
    }

    // Ask for one extra row: the seed is its own best match and is dropped below.
    const result = await client.execute(
      SIMILAR_QUERY,
      [seed.plot_embedding, seed.plot_embedding, limit + 1],
      { prepare: true, consistency: types.consistencies.one },
    );

    const neighbours = result.rows
      .filter((row) => row.movie_id !== id)
      .map((row) => ({
        movie_id: row.movie_id as string,
        title: row.title as string,
        release_year: row.release_year as number,
        score: Number((row.score as number).toFixed(4)),
      }));

    const best = neighbours[0]?.score ?? 0;
    const results = neighbours.filter((n) => n.score >= best - within);

    return {
      seed: { movie_id: id, title: seed.title as string, release_year: seed.release_year as number },
      results,
    };
  },
);

The handlers are async here, which is different from the Python weeks. The Node driver returns promises, so await doesn’t block the server, whereas the Python driver’s execute does.

Start the server from the app-ts/ directory:

npm start

Then ask for the default list, which is 10 movies within 0.02 of the best one:

curl "http://127.0.0.1:8000/movies/Q788822/similar"

The first five results are the same as the ones we saw at the start, followed by:

{ "movie_id": "Q211429", "title": "Up in the Air", "release_year": 2009, "score": 0.8442 },
{ "movie_id": "Q221113", "title": "A.I. Artificial Intelligence", "release_year": 2001, "score": 0.8423 },
{ "movie_id": "Q125933907", "title": "Companion", "release_year": 2025, "score": 0.841 },
{ "movie_id": "Q26698156", "title": "The Shape of Water", "release_year": 2017, "score": 0.8408 },
{ "movie_id": "Q190588", "title": "Love Actually", "release_year": 2003, "score": 0.84 }

An ID that isn’t in the table returns a 404, and a limit outside the range fails Fastify’s validation with a 400:

curl -s -w ' [%{http_code}]' "http://127.0.0.1:8000/movies/Q0/similar"
{"error":"No movie with id Q0"} [404]
curl -s -w ' [%{http_code}]' "http://127.0.0.1:8000/movies/Q788822/similar?limit=500"
{"statusCode":400,"code":"FST_ERR_VALIDATION","error":"Bad Request","message":"querystring/limit must be <= 50"} [400]

Run it on Cassandra 5.0

The same code runs on a Cassandra 5.0 cluster. Remove ASTRA_DB_TOKEN from .env, set CASSANDRA_HOSTS to your cluster and load the data with the loader. I ran the app on a cassandra:5.0 container (5.0.9) as well as Astra DB, and the movies came back in the same order with scores that matched to six decimal places.

Recap

  • “More like this” reads the seed’s vector from the table and uses it as the ANN OF vector, so it needs no embedding call.
  • Select similarity_cosine beside ANN OF, and drop the seed from its own results by asking for limit + 1 rows.
  • The Node.js driver binds only its own Vector type to a vector query.
  • CQL can’t filter on a score, so apply the threshold in code. Make it relative to the best neighbour, because embedding scores bunch together.

Info

Vector indexes are experimental in Cassandra 5.0. Storage Attached Index (SAI) vector indexes are not recommended for production use yet. Astra DB doesn’t print the 5.0 warning, but the restrictions apply there too. Week 9 compares 5.0 and Astra DB in full.

Next week, we look at the same CQL on Cassandra 5.0 and Astra DB, and where the fine print differs.

Try your own seed: find an ID with the CQL query above, then change limit and within and watch the list grow and shrink. The code from this post is in app-ts/ and the statements are in tutorials/week-08/ in the series repo. If you want next week’s post when it lands, follow me using the social buttons on the 8567.me homepage.


Movie facts from Wikidata, CC0. Plot text is fetched by the loader from each movie’s English Wikipedia article, CC BY-SA 4.0, and the wikipedia_url column links to each article.

Apache Cassandra, Cassandra, Apache, the Apache logo, and the Apache Cassandra project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.