Vector

The Vector class allows you to handle vectors and to execute distance and similarity calculations between them. Cette classe est disponible depuis le "class store" de 4D.

In the world of AIs, a vector is a sequence of numbers that enables a machine to understand and manipulate complex data. For a detailed overview of the role of vectors with AIs, you can refer to this page.

Understanding the different vector computations

The 4D.Vector class proposes three types of vector computations. The following table summarizes the main characteristics of each one:

	cosineSimilarity	dotSimilarity	euclideanDistance
Définition	Compares the orientation of two texts represented as vectors. The more they point in the same direction, the closer they are.	Sum of products between each vector dimension. It's like a weighted compatibility score.	Actual distance between two vectors, as if measured with a ruler.
Simple analogy	Are we talking about the same subject?	Are you talking about the same subject insistently?	Are you really far away from what I'm saying?
Exemple	Imagine you're looking for movies to watch on a video on-demand streaming service. Cosine similarity is used to compare your tastes (for example, you like action movies with a bit of comedy) to the movie descriptions in their database. It doesn't matter whether you're a "small" fan (you watch 1 film a month) or a "big" fan (you watch 10 films a week), what matters is whether the films have similar characteristics to what you like (action + comedy). The streaming service uses cosine similarity to recommend films that "point in the same direction" as your preferences.	Think of a search engine. When you type "chocolate cake recipe", the algorithm compares your query to web pages. The dot product can be used not only to check whether a page is talking about chocolate cakes (a similar direction to your search), but also to give more weight to pages that are highly relevant (for example, a page with lots of detailed content about chocolate cakes will have a greater "length" and therefore a higher score). A page with just one sentence on the subject will have a lower score.	Imagine a dating application. The algorithm can use Euclidean distance to compare your profile (your interests, age, location, etc.) with those of other users. If your profiles are very similar (for example, you both like hiking, pop music, and you live 5 km apart), the Euclidean distance between your profiles will be low, and the app will suggest this person as a good "match". Here, all differences (however small) count, not just the general direction of your tastes.

In any cases, it's a good idea to test the different vectors to determine which best suits your needs and data.

Vector object

Les objets vectoriels sont partagés, immuables et transmissibles.

.cosineSimilarity( vector : 4D.Vector ) : Real calculates the cosine similarity between the current 4D vector and the one you passed in the vector parameter
.dotSimilarity( vector : 4D.Vector ) : Real calculates the dot product of the current 4D vector and the one you passed in the vector parameter
.euclideanDistance( vector : 4D.Vector ) : Real calculates the Euclidean distance between the current 4D vector and the one you passed in the vector parameter
length : Integer the number of vector components
.toCollection() : Collection returns the vector components as a collection of reals

4D.Vector.new()

Historique

Release	Modifications
20 R10	Ajout

4D.Vector.new ( parameter : Collection ) : 4D.Vector

Paramètres	Type		Description
paramètres	Collection de réels	->	Collection de nombres réels représentant un vecteur
Résultat	4D.Vector	<-	Nouvel objet vectoriel

Description

The 4D.Vector.new() function creates and returns a new object of the 4D.Vector type.

In parameter, pass a collection of real numbers representing the vector to create. These values are provided by artifical intelligences and represent mathematically objects like words or data.

Exemple

Pour créer un vecteur :

var $vector := 4D.Vector.new([0.123; -0.456; 0.789]) 

You can access individual components or convert the entire vector back to a collection:

var $firstComponent := $vector[0]
var $collection := $vector.toCollection()

.cosineSimilarity()

.cosineSimilarity( vector : 4D.Vector ) : Real

Paramètres	Type		Description
vector	4D.Vector	->	Vecteur à comparer avec
Résultat	Real	<-	Distance entre les vecteurs

Description

The .cosineSimilarity() function calculates the cosine similarity between the current 4D vector and the one you passed in the vector parameter. Both vectors must have the same size.

This metric measures the angle between vectors and is commonly used to determine semantic similarity between texts. It is recommended for text embeddings, documents, sentences, and any data where direction matters more than magnitude (e.g. for semantic search or text classification).

Valeur retournée

• Range: -1 (opposite) to 1 (identical).
• Plus la valeur retournée est élevée, plus les vecteurs sont similaires.

Exemple 1

var $vector := 4D.Vector.new([0.123; -0.456; 0.789]) 
var $anotherVector := 4D.Vector.new([0.598; -0.951; 0.789])
var $similarity := $vector.cosineSimilarity($anotherVector)

Exemple 2

info

Cet exemple utilise l'extension [4D AIKit extension] (../aikit/overview.md) pour générer des embeddings.

var $model:="text-embedding-ada-002"
var $people:=ds.People.get(1)

$prompt:=String($people.Firstname)+" "+String($people.Lastname)+" was born on "+\
String($people.Birthday)+" and lives in "+String($people.Address)+", "+\
String($people.ZipCode)+", "+String($people.City)+", "+String($people.Country)+\
". Contact: "+String($people.email)+", "+String($people.Cell)+", "+\
String($people.Phone)+". Family IDs - Father: "+String($people.FatherID)+\
", Mother : "+String($people.MotherID)+", Partner: "+String($people.PartnerID)+"."

var $clientAI:=cs.AIKit.OpenAI.new(getAIKey())

// Calcul vectoriel avec 4D AIKit
var $result:=$clientAI.embeddings.create($prompt; $model)

// Création d'un objet 4D.vector
var $vector:=$result.vector

var $question:="I'm looking for John who lives in USA"

// Calcul vectoriel avec le composant 4D AIKit
var $questionVector:=$clientAI.embeddings.create($question; $model).vector

// calcul de similarité
If ($vector.cosineSimilarity($questionVector)>0.9)
  ALERT("Interesting result")
End if

// résultat réel : 0,7360136465949

.dotSimilarity()

.dotSimilarity( vector : 4D.Vector ) : Real

Paramètres	Type		Description
vector	4D.Vector	->	Vecteur à comparer avec
Résultat	Real	<-	Distance entre les vecteurs

Description

The .dotSimilarity() function calculates the dot product of the current 4D vector and the one you passed in the vector parameter. Both vectors must have the same size.

This metric reflects both similarity and magnitude, and is generally used in models where vector norms (magnitudes) vary. It is recommended for scenarios where embeddings have been fine-tuned with magnitude in mind (e.g., recommendation engines, scoring relevance).

Valeur retournée

• Dépend de la magnitude et de la direction des vecteurs
• Plus la valeur retournée est élevée, plus les vecteurs sont similaires.

Exemple

var $vector := 4D.Vector.new([0.123; -0.456; 0.789]) 
var $anotherVector := 4D.Vector.new([0.598; -0.951; 0.789])
var $score := $vector.dotSimilarity($anotherVector)

Exemple 2

info

Cet exemple utilise l'extension [4D AIKit extension] (../aikit/overview.md) pour générer des embeddings.

var $model:="text-embedding-ada-002"
var $clientAI:=cs.AIKit.OpenAI.new(getAIKey())

$documents:=[{text: "How to bake a chocolate cake"; similarity: 0}; \
{text: "Best hiking trails in the Alps"; similarity: 0}; \
{text: "Tips for learning 4D programming"; similarity: 0}; \
{text: "Top 10 sci-fi movies of all time"; similarity: 0}]

$question:="4D coding tutorials"

// Vector calculation with 4D AIKit component
$questionVector:=$clientAI.embeddings.create($question; $model).vector

For each ($document; $documents)
        // Vector calculation with 4D AIKit component
    $vector:=$clientAI.embeddings.create($document.text; $model).vector
        // similarity
    $document.similarity:=$vector.dotSimilarity($questionVector)
End for each

$documents:=$documents.orderBy("similarity desc")
ALERT("Best answer: "+$documents[0].text)

//$documents:
//{text:Tips for learning 4D programming,similarity:0.90409492325102}
//{text:Top 10 sci-fi movies of all time,similarity:0.75362527646035}
//{text:How to bake a chocolate cake,similarity:0.73664833336323}
//{text:Best hiking trails in the Alps,similarity:0.73138600461065}
 

.euclideanDistance()

.euclideanDistance( vector : 4D.Vector ) : Real

Paramètres	Type		Description
vector	4D.Vector	->	Vecteur à comparer avec
Résultat	Real	<-	Distance entre les vecteurs

Description

The .euclideanDistance() function calculates the Euclidean distance between the current 4D vector and the one you passed in the vector parameter. Both vectors must have the same size.

This measures the straight-line distance in the vector space. It is recommended for numeric or structured data embeddings, or when using models where proximity in raw space directly correlates with similarity.

Valeur retournée

• valeur retournée >= 0
• Plus la valeur retournée est faible, plus les vecteurs sont similaires.

Exemple 1

var $vector := 4D.Vector.new([0.123; -0.456; 0.789]) 
var $anotherVector := 4D.Vector.new([0.598; -0.951; 0.789])
var $distance := $vector.euclideanDistance($anotherVector)

Exemple 2

$places:=[\
{name: "Eiffel Tower"; coord: [48.8584; 200.2945]; similarity: 0}; \
{name: "Louvre Museum"; coord: [48.8606; 200.3376]; similarity: 0}; \
{name: "Notre-Dame"; coord: [48.8529; 200.35]; similarity: 0}; \
{name: "Montmartre"; coord: [48.8867; 200.3431]; similarity: 0}\
]

$userLocation:=[8.8566; 20.3522]
var $vector:=4D.Vector.new($userLocation)

For each ($place; $places)
  $place.similarity:=$vector.euclideanDistance(4D.Vector.new($place.coord))
End for each

$places:=$places.orderBy("similarity asc")
ALERT("Nearest monument: "+$places[0].name)

.length

length : Integer

Description

The .length property contains the number of vector components.

.toCollection()

.toCollection() : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Collection of real numbers representing the vector components

The .toCollection() function returns the vector components as a collection of reals.