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 OFquery 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:
| Package | What it does |
|---|---|
cassandra-driver 4.10.0 | The Node.js driver, which talks to Astra DB and Cassandra |
fastify 5.12.7 | The web framework for our one endpoint |
tsx 4.21.1 | Runs TypeScript files directly, with no build step |
typescript 5.9.3 | Checks 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 score | Movies kept |
|---|---|
| 0.85 | 2 |
| 0.80 | 672 |
| 0.75 | 998 |
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:
| Seed | within 0.01 | within 0.02 | within 0.03 |
|---|---|---|---|
| Her | 5 | 15 | 20 |
| Parasite | 1 | 7 | 20 |
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 OFvector, so it needs no embedding call. - Select
similarity_cosinebesideANN OF, and drop the seed from its own results by asking forlimit + 1rows. - The Node.js driver binds only its own
Vectortype 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.
