Table#

class Table#

A class representing an encrypted database. This Table supports the calculation of some data analysis functions on tabular data.

average_query(*args, **kwargs)#

Overloaded function.

average_query(self: pyhelayers.Table, average_field: str, field_to_compare: str, compare_value: pyhelayers.Field, ct: pyhelayers.ComparisonType) -> pyhelayers.FieldVector

Average of “average_field” elements, where “field_to_compare” satisfies the given comparison condition. Use post_process_average_query() to extract the required average from the return value of this function.

param average_field:

The name of the field to compute average for.

type average_field:

string

param field_to_compare:

The name of the field to apply the comparison condition on.

type field_to_compare:

string

param compare_value:

The value to compare with.

type compare_value:

Field

param ct:

The comparison type.

type ct:

comparison_type

rtype:

FieldVector

raises RuntimeError:

If this table was initialized with “inverse_optimsation_on” set to False and “ct” is not “IS_EQUAL”.
average_query(self: pyhelayers.Table, average_field: str) -> Tuple[pyhelayers.Field, int]

Average of “average_field” elements. Use post_process_average_query() to extract the required average from the return value of this function.

param average_field:

The name of the field to compute average for.

type average_field:

string

rtype:

tuple of (Field, int)

count_query(self: pyhelayers.Table, field_to_compare: str, compare_value: pyhelayers.Field, ct: pyhelayers.ComparisonType) → pyhelayers.Field#

Number of elements of “field_to_compare” satisfying the given comparison condition. Use postProcessCountQuery() to extract the count result from the return value of this function.

Parameters:

field_to_compare (string) – The name of the field to apply the comparison condition on.
compare_value (Field) – The value to compare with.
ct (comparison_type) – The comparison type.

Return type:

Field

Raises:

RuntimeError – If this table was initialized with “inverse_optimsation_on” set to False and “ct” is not “IS_EQUAL”.

create_compare_value(*args, **kwargs)#

Overloaded function.

create_compare_value(self: pyhelayers.Table, value_to_seek: int, column_name: str, is_signed: bool = False) -> pyhelayers.Field

Creates a hybrid bitwise value to be used in comparison queries.

param value_to_seek:

The compare value to use in the comparison.

type value_to_seek:

int

param column_name:

The name of the column which is intended to be compared with the given value.

type column_name:

string

param is_signed:

Whether the comparison value is signed. Defaults to False.

type is_signed:

bool

rtype:

Field
create_compare_value(self: pyhelayers.Table, value_to_seek: int, bit_len: int, is_signed: bool = False) -> pyhelayers.Field

Creates a hybrid bitwise value to be used in comparison queries.

param value_to_seek:

The compare value to use in the comparison.

type value_to_seek:

int

param bit_len:

The number of bits that should be used to represent the comparison value.

type bit_len:

int

param is_signed:

Whether the comparison value is signed. Defaults to False.

type is_signed:

bool

rtype:

Field

create_indicators_for_col(self: pyhelayers.Table, col_name: str, val_to_compare: pyhelayers.Field, ct: pyhelayers.ComparisonType, mult_by_mask: bool = False) → std::vector<std::shared_ptr<helayers::Field>, std::allocator<std::shared_ptr<helayers::Field> > >#

Applies the given comparison condition on the entries of the specified column, and returns a vector of indicators representing the comparison results. The ith Field in the returned vector contains the indicators corresponding to the ith Field in the specified column.

Parameters:

col_name (string) – The name of the column to create indicators for.
val_to_compare (Field) – The value to compare the column Fields with.
ct (FieldType) – comparison type.
mult_by_mask (bool) – If true, the resulting indicators will be multiplied by the stored mask. Defautls to False.

Return type:

FieldVector

get_cell_content(self: pyhelayers.Table, col_name: str, row_num: int) → pyhelayers.CTileVector#

Returns a CTile containing the column values in the Field with the given index.

Parameters:

col_name (string) – The name of the column to extract the content from.
row_num (int) – The index of the Field to be extracted from the specified column.

Return type:

CTileVector

get_num_of_rows(self: pyhelayers.Table) → int#: Returns the number of entries in this database.

mult_indicators(self: pyhelayers.Table, col_name: str, indicators: std::vector<std::shared_ptr<helayers::Field>, std::allocator<std::shared_ptr<helayers::Field> > >) → std::vector<std::shared_ptr<helayers::Field>, std::allocator<std::shared_ptr<helayers::Field> > >#

Multiplies the given set of indicators.

Parameters:

col_name (string) – The name of the column the given indicators are created for.
indicators (FieldVector) – The indicators to multiply.

Return type:

FieldVector

post_process_average_query(*args, **kwargs)#

Overloaded function.

post_process_average_query(self: pyhelayers.Table, query_res: pyhelayers.FieldVector) -> float

Applies post-processing on the result of an average_query and returns the average result. This function assumes that the HeContext stored in this Table object contains the secret key.

param query_res:

The result of an average_query.

type query_res:

FieldVector

rtype:

double
post_process_average_query(self: pyhelayers.Table, query_res: Tuple[pyhelayers.Field, int]) -> float

Applies post-processing on the result of an average_query and returns the average result. This function assumes that the HeContext stored in this Table object contains the secret key.

param query_res:

The result of an average_query.

type query_res:

tuple of (Field, int)

rtype:

double
post_process_average_query(self: pyhelayers.Table, query_res: Tuple[pyhelayers.FieldVector, int]) -> float

Applies post-processing on the result of a standard_deviation_query and returns the standard deviation result. This function assumes that the HeContext stored in this Table object contains the secret key.

param query_res:

The result of a standard_deviation_query.

type query_res:

tuple of (FieldVector, int)

rtype:

double

post_process_count_query(self: pyhelayers.Table, query_res: pyhelayers.Field) → int#

Applies post-processing on the result of a count_query and returns the counting result. This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: query_res (Field) – The result of a count_query.
Return type:: double

post_process_std_dev_query(self: pyhelayers.Table, query_res: pyhelayers.FieldVector) → float#

Applies post-processing on the result of a standard_deviation_query and returns the standard deviation result. This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: query_res (FieldVector) – The result of a standard_deviation_query.
Return type:: double

post_process_sum_query(self: pyhelayers.Table, query_res: pyhelayers.Field) → float#

Applies post-processing on the result of a sum_query and returns the sum value. This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: query_res (Field) – The result of a sum_query.
Return type:: double

post_process_sum_squares_query(self: pyhelayers.Table, query_res: pyhelayers.Field) → float#

Applies post-processing on the result of a sum_squares_query and returns the sum squares value. This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: query_res (Field) – The result of a sum_squares_query
Return type:: double

set_inverse_optimization(self: pyhelayers.Table, flag: bool) → None#

Sets inverseOptimisation flag to the given value.

Parameters:: flag (bool) – The value to set.
Return type:: void

standard_deviation_query(*args, **kwargs)#

Overloaded function.

standard_deviation_query(self: pyhelayers.Table, std_dev_field: str, field_to_compare: str, compare_value: pyhelayers.Field, ct: pyhelayers.ComparisonType) -> pyhelayers.FieldVector

Standard deviation of “std_dev_field” elements, where “field_to_compare” satisfies the given comparison condition. Use post_process_std_dev_query() to extract the required standard deviation from the return value of this function.

param std_dev_field:

The name of the field to compute standard deviation for.

type std_dev_field:

string

param field_to_compare:

The name of the field to apply the comparison condition on.

type field_to_compare:

string

param compare_value:

The value to compare with.

type compare_value:

Field

param ct:

The comparison type.

type ct:

comparison_type

rtype:

FieldVector

raises RuntimeError:

If this table was initialized with “inverse_optimsation_on” set to False and “ct” is not “IS_EQUAL”.
standard_deviation_query(self: pyhelayers.Table, std_dev_field: str) -> Tuple[pyhelayers.FieldVector, int]

Standard deviation of “std_dev_field” elements. Use post_process_std_dev_query() to extract the required standard deviation from the return value of this function.

param std_dev_field:

The name of the field to compute standard deviation for.

type std_dev_field:

string

rtype:

tuple of (FieldVector, int)

sum_query(*args, **kwargs)#

Overloaded function.

sum_query(self: pyhelayers.Table, field_to_sum: str, field_to_compare: str, compare_value: pyhelayers.Field, ct: pyhelayers.ComparisonType) -> pyhelayers.Field

Sum of “field_to_sum” elements, where “field_to_compare” satisfies the given comparison condition. Use post_process_sum_query() to extract the sum value from the return value of this function.

param field_to_sum:

The name of the field to sum.

type field_to_sum:

string

param field_to_compare:

The name of the field to apply the comparison condition on.

type field_to_compare:

string

param compare_value:

The value to compare with.

type compare_value:

Field

param ct:

The comparison type.

type ct:

comparison_type

rtype:

Field

raises RuntimeError:

If this table was initialized with “inverse_optimsation_on” set to False and “ct” is not “IS_EQUAL”.
sum_query(self: pyhelayers.Table, field_to_sum: str) -> pyhelayers.Field

Sum “field_to_sum” elements. Use post_process_sum_query() to extract the sum value from the return value of this function.

param field_to_sum:

The name of the column to sum.

type field_to_sum:

string

rtype:

Field

sum_squares_query(*args, **kwargs)#

Overloaded function.

sum_squares_query(self: pyhelayers.Table, sum_squares_field: str, field_to_compare: str, compare_value: pyhelayers.Field, ct: pyhelayers.ComparisonType) -> pyhelayers.Field

Sum squares of “sum_squares_field” elements, where “field_to_compare” satisfies the given comparison condition.

param sum_squares_field:

The name of the field to compute sum squares for.

type sum_squares_field:

string

param field_to_compare:

The name of the field to apply the comparison condition on.

type field_to_compare:

string

param compare_value:

The value to compare with.

type compare_value:

Field

param ct:

The comparison type.

type ct:

comparison_type

rtype:

Field

raises RuntimeError:

If this table was initialized with “inverse_optimsation_on” set to False and “ct” is not “IS_EQUAL”.
sum_squares_query(self: pyhelayers.Table, sum_squares_field: str) -> pyhelayers.Field

Sum of squares of “sum_squares_field” elements. Use post_process_sum_squares_query() to extract the sum value from the return value of this function.

param sum_squares_field:

The name of the column to compute sum squares for.

type sum_squares_field:

string

rtype:

Field

class Table : public helayers::Saveable#

A class representing an encrypted database.

This Table supports the calculation of some data analysis functions on tabular data.

Public Functions

inline Table(const HeContext &_he, bool oneSlotRes = false, bool inverseOptimisationOn = true)#

A constructor.

constructs an empty table.

Parameters:

_he – The HeContext.
oneSlotRes – If true, the results of queries (such as sum and count queries) will be aggregated to a single slot of the returned CTile. Otherwise, the results will be distributed among all of the CTile’s slots. Setting this argument to false would reduce the runtime of queries.
inverseOptimsationOn – Whether the inverse optimisation should be used.

Table(const HeContext &_he, std::ifstream &csvFile, bool oneSlotRes = false, bool inverseOptimisationOn = true)#

A constructor from csv File.

Parameters:

_he – The HeContext.
csvFile – A csv containing the database.
oneSlotRes – If true, the results of queries (such as sum and count queries) will be aggregated to a single slot of the returned CTile. Otherwise, the results will be distributed among all of the CTile’s slots. Setting this argument to false would reduce the runtime of queries.
inverseOptimisationOn – Whetehr the inverse optimisation should be used.

void encryptAndAddline(std::vector<std::vector<std::vector<double>>> &batch, int rows)#

Encrypts the given batch of database entries and stores them into the Table.

Parameters:

batch – The batch of entries to encrypt and add to the Table. The first dimension of this vector is for the different columns, the second one is for the entries of each column and the third one is for the bits of each entry.
row – The number of the records in the given batch.

std::vector<double> stringToVector(const std::string &fieldName, const std::string &fieldStr)#

Parses the given fieldStr into a vector of values corresponding to the field with the given name.

Parameters:

fieldName – The name of the field to be parsed.
fieldStr – The string value to be parsed.

Throws:

runtime_error – If the given string contain an unsupported filed type.

void addEmptyColumn(const std::string &colName, FieldType type)#

Adds an empty numirical column with the given parameters to the table.

This method is only relevant when the table is empty.

Parameters:

colName – The name of the empty column to be added.
FieldType – The type of the data represented by the column to be added.

void addEmptyBitwiseColumn(const std::string &colName, FieldType type, int bitLen)#

Adds an empty hybrid bitwise colum with the given parameters to the table.

Parameters:

colName – The name of the empty column to be added.
FieldType – The type of the data represented by the column to be added.
bitLen – The number of used bits in the column to be added.

std::vector<Field> parseAndEncryptLine(std::string line)#

Parses the given line into an encrypted Field.

Parameters:: line – The line to parse.

void addColumn(const std::string &colName, std::vector<Field> &colValues, FieldType type)#

Adds a column with the given parameters to the Table.

Parameters:

colName – The name of the empty column to add.
colValues – The entry values of the column to be added. Each batch of values should be represented by one Field.
FieldType – The type of the data represented by the column to be added.

void addFieldRow(std::vector<Field> &fieldRowToAdd, int rows = -1)#

Adds the given batch of database entries to the table.

The batch of entries should be represented by a vector of Fields, one Field for each column in the Table.

fieldRowToAdd A vector of Fields representing the values of the batch of entries to be added. The i-th element in this vector should contains the values to add to the i-th column of the Table.

row The number of used slots in the field. row=-1 if all slots are used.

const std::vector<CTile> &getCellContent(const std::string &colName, int rowNum)#

Returns a CTile containing the column values in the Field with the given index.

Parameters:

colName – The name of the column to extract the content from.
rowNum – The index of the Field to be extracted from the specified column.

std::vector<std::shared_ptr<Field>> createIndicatorsForCol(const std::string &colName, const Field &valToCompare, ComparisonType ct, bool multByMask = false) const#

Applies the given comparison condition on the entries of the specified column, and returns a vector of indicators representing the comparison results.

The ith Field in the returned vector contains the indicators corresponding to the ith Field in the specified column.

Parameters:

colName – The name of the column to create indicators for.
valToCompare – The value to compare the column Fields with.
ct – The comparison type.
multByMask – If true, the resulting indicators will be multiplied by the stored mask.

std::vector<std::shared_ptr<Field>> multIndicators(const std::string &colName, const std::vector<std::shared_ptr<Field>> &indicators) const#

Multiplies the given set of indicators.

Parameters:

colName – The name of the column the given indicators are created for.
indicators – The indicators to multiply.

Field sumQuery(const std::string &fieldToSum, const std::string &fieldToCompare, const Field &compareValue, ComparisonType ct) const#

Sum of “fieldToSum” elements, where “fieldToCompare” satisfies the given comparison condition.

Use postProcessSumQuery() to extract the sum value from the return value of this function.

Parameters:

fieldToSum – The field to sum.
fieldToCompare – The field to check whether its elements satisfy the given comparison condition.
compareValue – The value to compare with.

Throws:

runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

Field sumQuery(const std::string &fieldToSum) const#

Sum of “fieldToSum” elements.

Use postProcessSumQuery() to extract the sum value from the return value of this function.

Parameters:: fieldToSum – The field to sum.

double postProcessSumQuery(const Field &queryRes) const#

Applies post-processing on the result of a sumQuery and returns the sum value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of a sumQuery

Field sumSquaresQuery(const std::string &sumSqrsField, const std::string &fieldToCompare, const Field &compareValue, ComparisonType ct) const#

Sum of squares of “sumSqrsField” elements, where “fieldToCompare” satisfies the given comparison condition.

Use postProcessSumSquaresQuery() to extract the sum squares value from the return value of this function.

Parameters:

sumSqrsField – the field to compute the sum squares on.
fieldToCompare – the field to check whether its elements satisfy the given comparison condition.
compareValue – The value to compare with.

Throws:

runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

Field sumSquaresQuery(const std::string &sumSqrField) const#

Sum of squares of “sumSqrsField” elements.

Use postProcessSumSquaresQuery() to extract the sum squares value from the return value of this function.

Parameters:: sumSqrsField – The field to compute the sum squares on.
Throws:: runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

double postProcessSumSquaresQuery(const Field &queryRes) const#

Applies post-processing on the result of a sumSquaresQuery and returns the sum squares value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of a sumSqueresQuery

Field countQuery(const std::string &fieldToCompare, const Field &compareValue, ComparisonType ct) const#

Number of elements of “fieldToCompare” satisfying the given comparison condition.

Use postProcessCountQuery() to extract the count result from the return value of this function.

Parameters:: fieldToCompare – The field to count its elements that satisfy the given condition.
Throws:: runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

int postProcessCountQuery(const Field &queryRes) const#

Applies post-processing on the result of a countQuery and returns the counting result.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of a countQuery

std::vector<Field> averageQuery(const std::string &avgField, const std::string &fieldToCompare, const Field &compareValue, ComparisonType ct) const#

Average “avgField” elements, where “fieldToCompare” satisfies the given comparison condition.

Use postProcessAverageQuery() to extract the average value from the returned vector of fields.

Parameters:

fieldToCompare – The field to check whether its elements satisfy the given comparison condition.
compareValue – The value to compare with.

Throws:

runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false. functions)

std::pair<Field, int> averageQuery(const std::string &avgField) const#

Average “avgField” elements.

Use postProcessAverageQuery() to extract the rquired average value from the return value of this function.

Parameters:: avgField – The field to compute average on.
Throws:: runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

double postProcessAverageQuery(const std::vector<Field> &queryRes) const#

Applies post-processing on the result of an averageQuery and returns the average value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of an averageQuery

double postProcessAverageQuery(const std::pair<Field, int> &queryRes) const#

Applies post-processing on the result of an averageQuery and returns the average value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of an averageQuery

std::vector<Field> standardDeviationQuery(const std::string &stdDevField, const std::string &fieldToCompare, const Field &compareValue, ComparisonType ct) const#

Standrad deviation of “stdDevField” elements, where “fieldToCompare” satisfies the given comparison condition.

Use postProcessStdDevQuery() to extract the required standard deviation value from the returned vector of Fields.

Parameters:

avgField – the field to compute average on.
fieldToCompare – The field to check whether its elements satisfy the given comparison condition.
compareValue – The value to compare with.

Throws:

runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

std::pair<std::vector<Field>, int> standardDeviationQuery(const std::string &stdDevField) const#

Standrad deviation of “stdDevField” elements.

Use postProcessStdDevQuery() to extract the standard deviation value from the return value of this function.

Parameters:: avgField – The field to compute average on.
Throws:: runtime_error – If “ct” is of type “IS_GREATER” and “inverseOptimisation” is set to false.

double postProcessStdDevQuery(const std::vector<Field> &queryRes) const#

Applies post-processing on the result of a standardDeviationQuery and returns the standard deviation value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of a standardDeviationQuery

double postProcessStdDevQuery(const std::pair<std::vector<Field>, int> &queryRes) const#

Applies post-processing on the result of a standardDeviationQuery and returns the standard deviation value.

This function assumes that the HeContext stored in this Table object contains the secret key.

Parameters:: queryRes – The result of a standardDeviationQuery.

void buildColumnNamesAndTypes(std::vector<std::string> columnDescription)#

Parses the given column description string, and creates empty columns accordingly.

Parameters:: columnDescritopn – The column description string to parse.
Throws:: runtime_error – If the given strings have unsupported format.

Field createCompareValue(int valueToSeek, const std::string &columnName, bool isSigned = false) const#

Creates a hybrid bitwise value to be used in comparison queries.

Parameters:

valueToSeek – The compare value to use in the comparison.
columnName – The name of the column which is intended to be compared with this value.
isSigned – Whether the comparison value is signed.

Field createCompareValue(int valueToSeek, int bitLen, bool isSigned = false) const#

Creates a hybrid bitwise value to be used in comparison queries.

Parameters:

valueToSeek – The compare value to use in the comparison.
bitLen – The number of bits that should be used to represent the comparison value.
isSigned – Whether the comparison value is signed.

void setInverseOptimization(bool flag)#

Sets inverseOptimisation flag to the given value.

Parameters:: flag – The value to set.

inline int getNumOfRows() const#: Returns the number of entries in this database.

inline virtual int32_t getContextId() const override#

Returns the contextId of the HeContext this object was initialized with.

This contextId can be used, for example, to verify HeContext match when loading a saved Saveable object. Returning -1 signals no HeContext.

Public Static Functions

static std::vector<std::string> breakCSVLine(const std::string &line)#

Breaks the given line into different tokens.

The different tokens are assumed to be separated with a comma.

Parameters:: line – To break into different tokens.

static bool isInt(const std::string &s)#

Returns true if the given string represents an integer and false otherwise.

Parameters:: s – To check whether it represents an integer.

static std::vector<double> createBitwiseVector(int value, int bitLen)#

Returns a bitwise representation of the given value, using “bitLen” bits.

The first element of the returned vector represents the LSB.

Parameters:

value – To return a bitwise representation for.
bitLen – The number of bits to use in the bitwise representation.