From c2dfa764e13686df8d9b9f58ff5e86de702b5124 Mon Sep 17 00:00:00 2001 From: imilinovic Date: Tue, 31 Mar 2026 10:53:31 +0200 Subject: [PATCH 1/2] docs: add Point2d, Point3d, Enum, and ZonedDateTime to MGP API docs Add documentation for newly added types across C, C++, and Python API reference pages. Enum docs note the limitation that enum values can be received and inspected but not returned from procedures. --- pages/custom-query-modules/c/c-api.mdx | 509 +++++++++++++++++- pages/custom-query-modules/cpp/cpp-api.md | 274 ++++++++++ .../python/python-api.mdx | 98 ++++ 3 files changed, 879 insertions(+), 2 deletions(-) diff --git a/pages/custom-query-modules/c/c-api.mdx b/pages/custom-query-modules/c/c-api.mdx index e1a6c31cd..919708e53 100644 --- a/pages/custom-query-modules/c/c-api.mdx +++ b/pages/custom-query-modules/c/c-api.mdx @@ -50,7 +50,7 @@ Memgraph in order to use them. | | Name | | -------------- | -------------- | -| enum| **[mgp_value_type](#enum-mgp-value-type)** {MGP_VALUE_TYPE_NULL, MGP_VALUE_TYPE_BOOL, MGP_VALUE_TYPE_INT, MGP_VALUE_TYPE_DOUBLE, MGP_VALUE_TYPE_STRING, MGP_VALUE_TYPE_LIST, MGP_VALUE_TYPE_MAP, MGP_VALUE_TYPE_VERTEX, MGP_VALUE_TYPE_EDGE, MGP_VALUE_TYPE_PATH, MGP_VALUE_TYPE_DATE, MGP_VALUE_TYPE_LOCAL_TIME, MGP_VALUE_TYPE_LOCAL_DATE_TIME, MGP_VALUE_TYPE_DURATION, MGP_VALUE_TYPE_ZONED_DATE_TIME}
All available types that can be stored in a mgp_value. | +| enum| **[mgp_value_type](#enum-mgp-value-type)** {MGP_VALUE_TYPE_NULL, MGP_VALUE_TYPE_BOOL, MGP_VALUE_TYPE_INT, MGP_VALUE_TYPE_DOUBLE, MGP_VALUE_TYPE_STRING, MGP_VALUE_TYPE_LIST, MGP_VALUE_TYPE_MAP, MGP_VALUE_TYPE_VERTEX, MGP_VALUE_TYPE_EDGE, MGP_VALUE_TYPE_PATH, MGP_VALUE_TYPE_DATE, MGP_VALUE_TYPE_LOCAL_TIME, MGP_VALUE_TYPE_LOCAL_DATE_TIME, MGP_VALUE_TYPE_DURATION, MGP_VALUE_TYPE_ZONED_DATE_TIME, MGP_VALUE_TYPE_POINT_2D, MGP_VALUE_TYPE_POINT_3D, MGP_VALUE_TYPE_ENUM}
All available types that can be stored in a mgp_value. | | typedef void(*)(struct mgp_list *, struct mgp_graph *, struct mgp_result *, struct mgp_memory *) | **[mgp_proc_cb](#typedef-mgp-proc-cb)**
Entry-point for a query module read procedure, invoked through openCypher. | | typedef void(*)(struct mgp_list *, struct mgp_graph *, struct mgp_memory *) | **[mgp_proc_initializer](#typedef-mgp-proc-initializer)**
Initialization point for a query module read procedure, invoked before procedure. | | typedef void(*)() | **[mgp_proc_cleanup](#typedef-mgp-proc-cleanup)**
Cleanup for a query module read procedure | @@ -82,6 +82,9 @@ Memgraph in order to use them. | enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_local_date_time](#function-mgp-value-make-local-date-time)**(struct mgp_local_date_time * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_local_date_time. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_duration](#function-mgp-value-make-duration)**(struct mgp_duration * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_duration. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_zoned_date_time](#function-mgp-value-make-zoned-date-time)**(struct mgp_zoned_date_time * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_zoned_date_time. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_point_2d](#function-mgp-value-make-point-2d)**(struct mgp_point_2d * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_point_2d. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_point_3d](#function-mgp-value-make-point-3d)**(struct mgp_point_3d * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_point_3d. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_make_enum](#function-mgp-value-make-enum)**(struct mgp_enum * val, struct mgp_value ** result)
Create a mgp_value storing a mgp_enum. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_type](#function-mgp-value-get-type)**(struct mgp_value * val, enum [mgp_value_type](#enum-mgp-value-type) * result)
Get the type of the value contained in mgp_value. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_null](#function-mgp-value-is-null)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value represents `null`. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_bool](#function-mgp-value-is-bool)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a boolean. | @@ -98,6 +101,9 @@ Memgraph in order to use them. | enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_local_date_time](#function-mgp-value-is-local-date-time)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a local date-time. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_duration](#function-mgp-value-is-duration)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a duration. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_zoned_date_time](#function-mgp-value-is-zoned-date-time)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a zoned date-time. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_point_2d](#function-mgp-value-is-point-2d)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_point_3d](#function-mgp-value-is-point-3d)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_is_enum](#function-mgp-value-is-enum)**(struct mgp_value * val, int * result)
Result is non-zero if the given mgp_value stores an enum. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_bool](#function-mgp-value-get-bool)**(struct mgp_value * val, int * result)
Get the contained boolean value. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_int](#function-mgp-value-get-int)**(struct mgp_value * val, int64_t * result)
Get the contained integer. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_double](#function-mgp-value-get-double)**(struct mgp_value * val, double * result)
Get the contained double floating-point. | @@ -112,6 +118,9 @@ Memgraph in order to use them. | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_local_date_time](#function-mgp-value-get-local-date-time)**(struct mgp_value * val, struct mgp_local_date_time ** result)
Get the contained local date-time. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_duration](#function-mgp-value-get-duration)**(struct mgp_value * val, struct mgp_duration ** result)
Get the contained duration. | | enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_zoned_date_time](#function-mgp-value-get-zoned-date-time)**(struct mgp_value * val, struct mgp_zoned_date_time ** result)
Get the contained zoned date-time. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_point_2d](#function-mgp-value-get-point-2d)**(struct mgp_value * val, struct mgp_point_2d ** result)
Get the contained 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_point_3d](#function-mgp-value-get-point-3d)**(struct mgp_value * val, struct mgp_point_3d ** result)
Get the contained 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_value_get_enum](#function-mgp-value-get-enum)**(struct mgp_value * val, struct mgp_enum ** result)
Get the contained enum. | | enum [mgp_error](#variable-mgp-error) | **[mgp_list_make_empty](#function-mgp-list-make-empty)**(size_t capacity, struct mgp_memory * memory, struct mgp_list ** result)
Create an empty list with given capacity. | | void | **[mgp_list_destroy](#function-mgp-list-destroy)**(struct mgp_list * list)
Free the memory used by the given mgp_list and contained elements. | | enum [mgp_error](#variable-mgp-error) | **[mgp_list_contains_deleted](#function-mgp-list-contains-deleted)**(struct mgp_list * list, int * result)
Result is non-zero if the given list contains any deleted values, otherwise 0. | @@ -285,6 +294,27 @@ Memgraph in order to use them. | enum [mgp_error](#variable-mgp-error) | **[mgp_duration_neg](#function-mgp-duration-neg)**(struct mgp_duration * dur, struct mgp_memory * memory, struct mgp_duration ** result)
Apply unary minus operator to the duration. | | enum [mgp_error](#variable-mgp-error) | **[mgp_duration_add](#function-mgp-duration-add)**(struct mgp_duration * first, struct mgp_duration * second, struct mgp_memory * memory, struct mgp_duration ** result)
Add two durations. | | enum [mgp_error](#variable-mgp-error) | **[mgp_duration_sub](#function-mgp-duration-sub)**(struct mgp_duration * first, struct mgp_duration * second, struct mgp_memory * memory, struct mgp_duration ** result)
Subtract two durations. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_make](#function-mgp-point-2d-make)**(double x, double y, uint16_t srid, struct mgp_memory * memory, struct mgp_point_2d ** result)
Create a 2D point with given coordinates and SRID. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_copy](#function-mgp-point-2d-copy)**(struct mgp_point_2d * point, struct mgp_memory * memory, struct mgp_point_2d ** result)
Copy a mgp_point_2d. | +| void | **[mgp_point_2d_destroy](#function-mgp-point-2d-destroy)**(struct mgp_point_2d * point)
Free the memory used by a mgp_point_2d. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_equal](#function-mgp-point-2d-equal)**(struct mgp_point_2d * first, struct mgp_point_2d * second, int * result)
Result is non-zero if given 2D points are equal, otherwise 0. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_get_x](#function-mgp-point-2d-get-x)**(struct mgp_point_2d * point, double * result)
Get the x coordinate of a 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_get_y](#function-mgp-point-2d-get-y)**(struct mgp_point_2d * point, double * result)
Get the y coordinate of a 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_2d_get_srid](#function-mgp-point-2d-get-srid)**(struct mgp_point_2d * point, uint16_t * result)
Get the SRID of a 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_make](#function-mgp-point-3d-make)**(double x, double y, double z, uint16_t srid, struct mgp_memory * memory, struct mgp_point_3d ** result)
Create a 3D point with given coordinates and SRID. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_copy](#function-mgp-point-3d-copy)**(struct mgp_point_3d * point, struct mgp_memory * memory, struct mgp_point_3d ** result)
Copy a mgp_point_3d. | +| void | **[mgp_point_3d_destroy](#function-mgp-point-3d-destroy)**(struct mgp_point_3d * point)
Free the memory used by a mgp_point_3d. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_equal](#function-mgp-point-3d-equal)**(struct mgp_point_3d * first, struct mgp_point_3d * second, int * result)
Result is non-zero if given 3D points are equal, otherwise 0. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_get_x](#function-mgp-point-3d-get-x)**(struct mgp_point_3d * point, double * result)
Get the x coordinate of a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_get_y](#function-mgp-point-3d-get-y)**(struct mgp_point_3d * point, double * result)
Get the y coordinate of a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_get_z](#function-mgp-point-3d-get-z)**(struct mgp_point_3d * point, double * result)
Get the z coordinate of a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_point_3d_get_srid](#function-mgp-point-3d-get-srid)**(struct mgp_point_3d * point, uint16_t * result)
Get the SRID of a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_enum_make](#function-mgp-enum-make)**(const char * type_name, const char * value_name, struct mgp_memory * memory, struct mgp_enum ** result)
Create an enum value from type and value name strings. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_enum_copy](#function-mgp-enum-copy)**(struct mgp_enum * val, struct mgp_memory * memory, struct mgp_enum ** result)
Copy a mgp_enum. | +| void | **[mgp_enum_destroy](#function-mgp-enum-destroy)**(struct mgp_enum * val)
Free the memory used by a mgp_enum. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_enum_equal](#function-mgp-enum-equal)**(struct mgp_enum * first, struct mgp_enum * second, int * result)
Result is non-zero if given enum values are equal, otherwise 0. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_enum_get_type_name](#function-mgp-enum-get-type-name)**(struct mgp_enum * val, const char ** result)
Get the type name of the enum value. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_enum_get_value_name](#function-mgp-enum-get-value-name)**(struct mgp_enum * val, const char ** result)
Get the value name of the enum value. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_any](#function-mgp-type-any)**(struct mgp_type ** result)
Get the type representing any value that isn't `null`. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_bool](#function-mgp-type-bool)**(struct mgp_type ** result)
Get the type representing boolean values. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_string](#function-mgp-type-string)**(struct mgp_type ** result)
Get the type representing character string values. | @@ -300,6 +330,10 @@ Memgraph in order to use them. | enum [mgp_error](#variable-mgp-error) | **[mgp_type_local_time](#function-mgp-type-local-time)**(struct mgp_type ** result)
Get the type representing a local time. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_local_date_time](#function-mgp-type-local-date-time)**(struct mgp_type ** result)
Get the type representing a local date-time. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_duration](#function-mgp-type-duration)**(struct mgp_type ** result)
Get the type representing a duration. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_type_zoned_date_time](#function-mgp-type-zoned-date-time)**(struct mgp_type ** result)
Get the type representing a zoned date-time. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_type_point_2d](#function-mgp-type-point-2d)**(struct mgp_type ** result)
Get the type representing a 2D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_type_point_3d](#function-mgp-type-point-3d)**(struct mgp_type ** result)
Get the type representing a 3D point. | +| enum [mgp_error](#variable-mgp-error) | **[mgp_type_enum](#function-mgp-type-enum)**(struct mgp_type ** result)
Get the type representing an enum value. | | enum [mgp_error](#variable-mgp-error) | **[mgp_type_nullable](#function-mgp-type-nullable)**(struct mgp_type * type, struct mgp_type ** result)
Build a type representing either a `null` value or a value of given `type`. | | enum [mgp_error](#variable-mgp-error) | **[mgp_module_add_read_procedure](#function-mgp-module-add-read-procedure)**(struct mgp_module * module, const char * name, [mgp_proc_cb](#typedef-mgp-proc-cb) cb, struct mgp_proc ** result)
Register a read-only procedure to a module. | | enum [mgp_error](#variable-mgp-error) | **[mgp_module_add_write_procedure](#function-mgp-module-add-write-procedure)**(struct mgp_module * module, const char * name, [mgp_proc_cb](#typedef-mgp-proc-cb) cb, struct mgp_proc ** result)
Register a writeable procedure to a module. | @@ -624,6 +658,9 @@ All available types that can be stored in a mgp_value. | MGP_VALUE_TYPE_LOCAL_DATE_TIME | | MGP_VALUE_TYPE_DURATION | | MGP_VALUE_TYPE_ZONED_DATE_TIME | +| MGP_VALUE_TYPE_POINT_2D | +| MGP_VALUE_TYPE_POINT_3D | +| MGP_VALUE_TYPE_ENUM | ### typedef mgp_proc_cb [#typedef-mgp-proc-cb]### typedef mgp_proc_initializer [#typedef-mgp-proc-initializer]### typedef mgp_proc_cleanup [#typedef-mgp-proc-cleanup] ```cpp @@ -941,6 +978,62 @@ zoned date-time. `MGP_ERROR_UNABLE_TO_ALLOCATE` is returned if unable to allocat a `mgp_value`. +### mgp_value_make_point_2d [#function-mgp-value-make-point-2d] +```cpp +enum mgp_error mgp_value_make_point_2d( + struct mgp_point_2d * val, + struct mgp_value ** result +) +``` + +Create a `mgp_value` storing a `mgp_point_2d`. + +You need to free the instance through `mgp_value_destroy`. The ownership of the +2D point is transferred to the created `mgp_value` and destroying the +`mgp_value` will destroy the `mgp_point_2d`. Therefore, if a `mgp_value` is +successfully created you must not call `mgp_point_2d_destroy` on the given +point. `MGP_ERROR_UNABLE_TO_ALLOCATE` is returned if unable to allocate +a `mgp_value`. + + +### mgp_value_make_point_3d [#function-mgp-value-make-point-3d] +```cpp +enum mgp_error mgp_value_make_point_3d( + struct mgp_point_3d * val, + struct mgp_value ** result +) +``` + +Create a `mgp_value` storing a `mgp_point_3d`. + +You need to free the instance through `mgp_value_destroy`. The ownership of the +3D point is transferred to the created `mgp_value` and destroying the +`mgp_value` will destroy the `mgp_point_3d`. Therefore, if a `mgp_value` is +successfully created you must not call `mgp_point_3d_destroy` on the given +point. `MGP_ERROR_UNABLE_TO_ALLOCATE` is returned if unable to allocate +a `mgp_value`. + + +### mgp_value_make_enum [#function-mgp-value-make-enum] +```cpp +enum mgp_error mgp_value_make_enum( + struct mgp_enum * val, + struct mgp_value ** result +) +``` + +Create a `mgp_value` storing a `mgp_enum`. + +You need to free the instance through `mgp_value_destroy`. The ownership of the +enum is transferred to the created `mgp_value` and destroying the +`mgp_value` will destroy the `mgp_enum`. Therefore, if a `mgp_value` is +successfully created you must not call `mgp_enum_destroy` on the given +enum. `MGP_ERROR_UNABLE_TO_ALLOCATE` is returned if unable to allocate +a `mgp_value`. + +> **Note:** Enum values can be received as procedure input and inspected, but cannot be returned from procedures. + + ### mgp_value_get_type [#function-mgp-value-get-type] ```cpp enum mgp_error mgp_value_get_type( @@ -1148,6 +1241,45 @@ Result is non-zero if the given `mgp_value` stores a zoned date-time. Current implementation always returns without errors. +### mgp_value_is_point_2d [#function-mgp-value-is-point-2d] +```cpp +enum mgp_error mgp_value_is_point_2d( + struct mgp_value * val, + int * result +) +``` + +Result is non-zero if the given `mgp_value` stores a 2D point. + +Current implementation always returns without errors. + + +### mgp_value_is_point_3d [#function-mgp-value-is-point-3d] +```cpp +enum mgp_error mgp_value_is_point_3d( + struct mgp_value * val, + int * result +) +``` + +Result is non-zero if the given `mgp_value` stores a 3D point. + +Current implementation always returns without errors. + + +### mgp_value_is_enum [#function-mgp-value-is-enum] +```cpp +enum mgp_error mgp_value_is_enum( + struct mgp_value * val, + int * result +) +``` + +Result is non-zero if the given `mgp_value` stores an enum value. + +Current implementation always returns without errors. + + ### mgp_value_get_bool [#function-mgp-value-get-bool] ```cpp enum mgp_error mgp_value_get_bool( @@ -1330,6 +1462,45 @@ Get the contained zoned date-time. Result is undefined if `mgp_value` does not contain the expected type. Current implementation always returns without errors. +### mgp_value_get_point_2d [#function-mgp-value-get-point-2d] +```cpp +enum mgp_error mgp_value_get_point_2d( + struct mgp_value * val, + struct mgp_point_2d ** result +) +``` + +Get the contained 2D point. + +Result is undefined if `mgp_value` does not contain the expected type. Current implementation always returns without errors. + + +### mgp_value_get_point_3d [#function-mgp-value-get-point-3d] +```cpp +enum mgp_error mgp_value_get_point_3d( + struct mgp_value * val, + struct mgp_point_3d ** result +) +``` + +Get the contained 3D point. + +Result is undefined if `mgp_value` does not contain the expected type. Current implementation always returns without errors. + + +### mgp_value_get_enum [#function-mgp-value-get-enum] +```cpp +enum mgp_error mgp_value_get_enum( + struct mgp_value * val, + struct mgp_enum ** result +) +``` + +Get the contained enum value. + +Result is undefined if `mgp_value` does not contain the expected type. Current implementation always returns without errors. + + ### mgp_list_make_empty [#function-mgp-list-make-empty] ```cpp enum mgp_error mgp_list_make_empty( @@ -3532,6 +3703,287 @@ Subtract two durations. Resulting pointer must be freed with mgp_duration_destroy. Return MGP_ERROR_INVALID_ARGUMENT if the operation results in an invalid duration. Return MGP_ERROR_UNABLE_TO_ALLOCATE if unable to allocate a mgp_duration. +### mgp_point_2d_make [#function-mgp-point-2d-make] +```cpp +enum mgp_error mgp_point_2d_make( + double x, + double y, + uint16_t srid, + struct mgp_memory * memory, + struct mgp_point_2d ** result +) +``` + +Create a 2D point with given x and y coordinates and spatial reference identifier (SRID). + +Supported SRIDs: 4326 (WGS-84), 7203 (Cartesian 2D). Resulting point must be freed with `mgp_point_2d_destroy`. Return `MGP_ERROR_INVALID_ARGUMENT` if the SRID is not valid. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_point_2d`. + + +### mgp_point_2d_copy [#function-mgp-point-2d-copy] +```cpp +enum mgp_error mgp_point_2d_copy( + struct mgp_point_2d * point, + struct mgp_memory * memory, + struct mgp_point_2d ** result +) +``` + +Copy a `mgp_point_2d`. + +Resulting pointer must be freed with `mgp_point_2d_destroy`. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_point_2d`. + + +### mgp_point_2d_destroy [#function-mgp-point-2d-destroy] +```cpp +void mgp_point_2d_destroy( + struct mgp_point_2d * point +) +``` + +Free the memory used by a `mgp_point_2d`. + + +### mgp_point_2d_equal [#function-mgp-point-2d-equal] +```cpp +enum mgp_error mgp_point_2d_equal( + struct mgp_point_2d * first, + struct mgp_point_2d * second, + int * result +) +``` + +Result is non-zero if given 2D points are equal, otherwise 0. + +Current implementation always returns without errors. + + +### mgp_point_2d_get_x [#function-mgp-point-2d-get-x] +```cpp +enum mgp_error mgp_point_2d_get_x( + struct mgp_point_2d * point, + double * result +) +``` + +Get the x coordinate of a 2D point. + +Current implementation always returns without errors. + + +### mgp_point_2d_get_y [#function-mgp-point-2d-get-y] +```cpp +enum mgp_error mgp_point_2d_get_y( + struct mgp_point_2d * point, + double * result +) +``` + +Get the y coordinate of a 2D point. + +Current implementation always returns without errors. + + +### mgp_point_2d_get_srid [#function-mgp-point-2d-get-srid] +```cpp +enum mgp_error mgp_point_2d_get_srid( + struct mgp_point_2d * point, + uint16_t * result +) +``` + +Get the SRID (spatial reference identifier) of a 2D point. + +Current implementation always returns without errors. + + +### mgp_point_3d_make [#function-mgp-point-3d-make] +```cpp +enum mgp_error mgp_point_3d_make( + double x, + double y, + double z, + uint16_t srid, + struct mgp_memory * memory, + struct mgp_point_3d ** result +) +``` + +Create a 3D point with given x, y, and z coordinates and spatial reference identifier (SRID). + +Supported SRIDs: 4979 (WGS-84 3D), 9157 (Cartesian 3D). Resulting point must be freed with `mgp_point_3d_destroy`. Return `MGP_ERROR_INVALID_ARGUMENT` if the SRID is not valid. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_point_3d`. + + +### mgp_point_3d_copy [#function-mgp-point-3d-copy] +```cpp +enum mgp_error mgp_point_3d_copy( + struct mgp_point_3d * point, + struct mgp_memory * memory, + struct mgp_point_3d ** result +) +``` + +Copy a `mgp_point_3d`. + +Resulting pointer must be freed with `mgp_point_3d_destroy`. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_point_3d`. + + +### mgp_point_3d_destroy [#function-mgp-point-3d-destroy] +```cpp +void mgp_point_3d_destroy( + struct mgp_point_3d * point +) +``` + +Free the memory used by a `mgp_point_3d`. + + +### mgp_point_3d_equal [#function-mgp-point-3d-equal] +```cpp +enum mgp_error mgp_point_3d_equal( + struct mgp_point_3d * first, + struct mgp_point_3d * second, + int * result +) +``` + +Result is non-zero if given 3D points are equal, otherwise 0. + +Current implementation always returns without errors. + + +### mgp_point_3d_get_x [#function-mgp-point-3d-get-x] +```cpp +enum mgp_error mgp_point_3d_get_x( + struct mgp_point_3d * point, + double * result +) +``` + +Get the x coordinate of a 3D point. + +Current implementation always returns without errors. + + +### mgp_point_3d_get_y [#function-mgp-point-3d-get-y] +```cpp +enum mgp_error mgp_point_3d_get_y( + struct mgp_point_3d * point, + double * result +) +``` + +Get the y coordinate of a 3D point. + +Current implementation always returns without errors. + + +### mgp_point_3d_get_z [#function-mgp-point-3d-get-z] +```cpp +enum mgp_error mgp_point_3d_get_z( + struct mgp_point_3d * point, + double * result +) +``` + +Get the z coordinate of a 3D point. + +Current implementation always returns without errors. + + +### mgp_point_3d_get_srid [#function-mgp-point-3d-get-srid] +```cpp +enum mgp_error mgp_point_3d_get_srid( + struct mgp_point_3d * point, + uint16_t * result +) +``` + +Get the SRID (spatial reference identifier) of a 3D point. + +Current implementation always returns without errors. + + +### mgp_enum_make [#function-mgp-enum-make] +```cpp +enum mgp_error mgp_enum_make( + const char * type_name, + const char * value_name, + struct mgp_memory * memory, + struct mgp_enum ** result +) +``` + +Create an enum value from type and value name strings. + +Resulting enum must be freed with `mgp_enum_destroy`. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_enum`. + +> **Note:** Enum values can be received as procedure input and inspected, but cannot be returned from procedures. + + +### mgp_enum_copy [#function-mgp-enum-copy] +```cpp +enum mgp_error mgp_enum_copy( + struct mgp_enum * val, + struct mgp_memory * memory, + struct mgp_enum ** result +) +``` + +Copy a `mgp_enum`. + +Resulting pointer must be freed with `mgp_enum_destroy`. Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate a `mgp_enum`. + + +### mgp_enum_destroy [#function-mgp-enum-destroy] +```cpp +void mgp_enum_destroy( + struct mgp_enum * val +) +``` + +Free the memory used by the given `mgp_enum`. + + +### mgp_enum_equal [#function-mgp-enum-equal] +```cpp +enum mgp_error mgp_enum_equal( + struct mgp_enum * first, + struct mgp_enum * second, + int * result +) +``` + +Result is non-zero if the given enum values are equal (same type name and value name), otherwise 0. + +Current implementation always returns without errors. + + +### mgp_enum_get_type_name [#function-mgp-enum-get-type-name] +```cpp +enum mgp_error mgp_enum_get_type_name( + struct mgp_enum * val, + const char ** result +) +``` + +Get the type name of the enum value (e.g. `"Status"` for `Status.Active`). + +Current implementation always returns without errors. + + +### mgp_enum_get_value_name [#function-mgp-enum-get-value-name] +```cpp +enum mgp_error mgp_enum_get_value_name( + struct mgp_enum * val, + const char ** result +) +``` + +Get the value name of the enum value (e.g. `"Active"` for `Status.Active`). + +Current implementation always returns without errors. + + ### mgp_type_any [#function-mgp-type-any] ```cpp enum mgp_error mgp_type_any( @@ -3719,6 +4171,56 @@ Get the type representing a duration. Return MGP_ERROR_UNABLE_TO_ALLOCATE if unable to allocate the new type. +### mgp_type_zoned_date_time [#function-mgp-type-zoned-date-time] +```cpp +enum mgp_error mgp_type_zoned_date_time( + struct mgp_type ** result +) +``` + +Get the type representing a zoned date-time. + +Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate the new type. + + +### mgp_type_point_2d [#function-mgp-type-point-2d] +```cpp +enum mgp_error mgp_type_point_2d( + struct mgp_type ** result +) +``` + +Get the type representing a 2D point. + +Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate the new type. + + +### mgp_type_point_3d [#function-mgp-type-point-3d] +```cpp +enum mgp_error mgp_type_point_3d( + struct mgp_type ** result +) +``` + +Get the type representing a 3D point. + +Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate the new type. + + +### mgp_type_enum [#function-mgp-type-enum] +```cpp +enum mgp_error mgp_type_enum( + struct mgp_type ** result +) +``` + +Get the type representing an enum value. + +Use this when declaring procedure parameters that accept enum values. Enum values can be received as input and inspected (type name, value name), but cannot be returned from procedures. + +Return `MGP_ERROR_UNABLE_TO_ALLOCATE` if unable to allocate the new type. + + ### mgp_type_nullable [#function-mgp-type-nullable] ```cpp enum mgp_error mgp_type_nullable( @@ -4240,7 +4742,10 @@ enum mgp_value_type { MGP_VALUE_TYPE_LOCAL_TIME, MGP_VALUE_TYPE_LOCAL_DATE_TIME, MGP_VALUE_TYPE_DURATION, - MGP_VALUE_TYPE_ZONED_DATE_TIME + MGP_VALUE_TYPE_ZONED_DATE_TIME, + MGP_VALUE_TYPE_POINT_2D, + MGP_VALUE_TYPE_POINT_3D, + MGP_VALUE_TYPE_ENUM }; void mgp_value_destroy(struct mgp_value *val); diff --git a/pages/custom-query-modules/cpp/cpp-api.md b/pages/custom-query-modules/cpp/cpp-api.md index ea19b0c09..454a7e927 100644 --- a/pages/custom-query-modules/cpp/cpp-api.md +++ b/pages/custom-query-modules/cpp/cpp-api.md @@ -1801,6 +1801,250 @@ Object is hashable using std::hash ``` +### Point2d + +Represents a 2D point with x and y coordinates and a spatial reference identifier (SRID). + +#### Constructors + +Creates a Point2d object from the copy of the given `mgp_point_2d`. + +```cpp +explicit Point2d(mgp_point_2d *ptr) +explicit Point2d(const mgp_point_2d *const_ptr) +``` + +Creates a Point2d object with the given `x`, `y` coordinates and `srid`. + +```cpp +Point2d(double x, double y, uint16_t srid) +``` + +Supported SRIDs: 4326 (WGS-84), 7203 (Cartesian 2D). + +Copy and move constructors: + +```cpp +Point2d(const Point2d &other) +Point2d(Point2d &&other) noexcept +``` + +#### Member functions + +| Name | Description | +| ------- | ------------------------------------------------- | +| `X` | Returns the x coordinate. | +| `Y` | Returns the y coordinate. | +| `Srid` | Returns the spatial reference identifier (SRID). | +| `ToString` | Returns the point's string representation. | + +##### X + +Returns the x coordinate of the point. + +```cpp +double X() const +``` + +##### Y + +Returns the y coordinate of the point. + +```cpp +double Y() const +``` + +##### Srid + +Returns the SRID (spatial reference identifier) of the point. + +```cpp +uint16_t Srid() const +``` + +##### ToString + +Returns the point's string representation. + +```cpp +std::string ToString() const +``` + +#### Operators + +| Name | Description | +| ------------ | -------------------- | +| `operator==` | comparison operator | + +Object is hashable using + +```cpp +std::hash +``` + +### Point3d + +Represents a 3D point with x, y, and z coordinates and a spatial reference identifier (SRID). + +#### Constructors + +Creates a Point3d object from the copy of the given `mgp_point_3d`. + +```cpp +explicit Point3d(mgp_point_3d *ptr) +explicit Point3d(const mgp_point_3d *const_ptr) +``` + +Creates a Point3d object with the given `x`, `y`, `z` coordinates and `srid`. + +```cpp +Point3d(double x, double y, double z, uint16_t srid) +``` + +Supported SRIDs: 4979 (WGS-84 3D), 9157 (Cartesian 3D). + +Copy and move constructors: + +```cpp +Point3d(const Point3d &other) +Point3d(Point3d &&other) noexcept +``` + +#### Member functions + +| Name | Description | +| ------- | ------------------------------------------------- | +| `X` | Returns the x coordinate. | +| `Y` | Returns the y coordinate. | +| `Z` | Returns the z coordinate. | +| `Srid` | Returns the spatial reference identifier (SRID). | +| `ToString` | Returns the point's string representation. | + +##### X + +Returns the x coordinate of the point. + +```cpp +double X() const +``` + +##### Y + +Returns the y coordinate of the point. + +```cpp +double Y() const +``` + +##### Z + +Returns the z coordinate of the point. + +```cpp +double Z() const +``` + +##### Srid + +Returns the SRID (spatial reference identifier) of the point. + +```cpp +uint16_t Srid() const +``` + +##### ToString + +Returns the point's string representation. + +```cpp +std::string ToString() const +``` + +#### Operators + +| Name | Description | +| ------------ | -------------------- | +| `operator==` | comparison operator | + +Object is hashable using + +```cpp +std::hash +``` + +### Enum + +Represents an enum value with a type name and value name. + +> **Note:** Enum values can be received as procedure input and inspected (type name, value name, equality), but cannot be returned from procedures. + +#### Constructors + +Creates an Enum object from the copy of the given `mgp_enum`. + +```cpp +explicit Enum(mgp_enum *ptr) +explicit Enum(const mgp_enum *const_ptr) +``` + +Creates an Enum from type name and value name strings. + +```cpp +Enum(std::string_view type_name, std::string_view value_name) +``` + +Copy and move constructors: + +```cpp +Enum(const Enum &other) +Enum(Enum &&other) noexcept +``` + +#### Member functions + +| Name | Description | +| ----------- | ------------------------------------------------ | +| `TypeName` | Returns the type name of the enum. | +| `ValueName` | Returns the value name of the enum. | +| `ToString` | Returns the enum's string representation. | + +##### TypeName + +Returns the type name of the enum (e.g. `"Status"` for `Status.Active`). + +```cpp +std::string_view TypeName() const +``` + +##### ValueName + +Returns the value name of the enum (e.g. `"Active"` for `Status.Active`). + +```cpp +std::string_view ValueName() const +``` + +##### ToString + +Returns the enum's string representation. + +```cpp +std::string ToString() const +``` + +#### Operators + +| Name | Description | +| ------------ | -------------------- | +| `operator==` | comparison operator | +| `operator!=` | comparison operator | + +Object is hashable using + +```cpp +std::hash +``` + ### Path A path is a data structure consisting of alternating nodes and relationships, with the start @@ -2428,6 +2672,21 @@ Duration ValueDuration() const Duration ValueDuration() ``` +```cpp +Point2d ValuePoint2d() const +Point2d ValuePoint2d() +``` + +```cpp +Point3d ValuePoint3d() const +Point3d ValuePoint3d() +``` + +```cpp +Enum ValueEnum() const +Enum ValueEnum() +``` + ##### Is[TYPE] Returns whether the value stored in the `Value` object is of the type in the call. @@ -2496,6 +2755,18 @@ bool IsZonedDateTime() const bool IsDuration() const ``` +```cpp +bool IsPoint2d() const +``` + +```cpp +bool IsPoint3d() const +``` + +```cpp +bool IsEnum() const +``` + ##### ToString Returns the value's string representation. It does this by finding the type of the object wrapped inside the Value object, calling its ToString() function or casting the object to string, depending on it's type. The table below shows the appropriate action for each type. @@ -2568,6 +2839,9 @@ The types are listed and described [in the reference guide](/fundamentals/data-t - `Type::LocalDateTime` - `Type::ZonedDateTime` - `Type::Duration` +- `Type::Point2d` +- `Type::Point3d` +- `Type::Enum` Additionally, operator<< is overloaded for Type enum, and usage of this operator will print the type represented by mgp::Type enum. diff --git a/pages/custom-query-modules/python/python-api.mdx b/pages/custom-query-modules/python/python-api.mdx index 2a8d90186..aea6c6c3e 100644 --- a/pages/custom-query-modules/python/python-api.mdx +++ b/pages/custom-query-modules/python/python-api.mdx @@ -1155,6 +1155,104 @@ def __init__(**kwargs) Initialize with name=value fields in kwargs. +## Point2d + +```python +class Point2d() +``` + +Type annotation marker for 2D spatial point values in procedure signatures. + +At runtime, 2D points are represented as objects with `x`, `y`, and `srid` properties. +This class is used solely in type annotations to declare that a procedure parameter or +return field expects a 2D point value. + +Supported SRIDs: 4326 (WGS-84), 7203 (Cartesian 2D). + +**Example usage** + +```python +import mgp + +@mgp.read_proc +def my_proc(ctx: mgp.ProcCtx, location: mgp.Point2d) -> mgp.Record(result=mgp.Point2d): + return mgp.Record(result=location) +``` + +## Point3d + +```python +class Point3d() +``` + +Type annotation marker for 3D spatial point values in procedure signatures. + +At runtime, 3D points are represented as objects with `x`, `y`, `z`, and `srid` properties. +This class is used solely in type annotations to declare that a procedure parameter or +return field expects a 3D point value. + +Supported SRIDs: 4979 (WGS-84 3D), 9157 (Cartesian 3D). + +**Example usage** + +```python +import mgp + +@mgp.read_proc +def my_proc(ctx: mgp.ProcCtx, location: mgp.Point3d) -> mgp.Record(result=mgp.Point3d): + return mgp.Record(result=location) +``` + +## ZonedDateTime + +```python +class ZonedDateTime() +``` + +Type annotation marker for zoned date-time values in procedure signatures. + +At runtime, zoned date-time values are represented as `datetime.datetime` objects with +`tzinfo` set. This class exists so that procedure signatures can distinguish zoned +date-times from local date-times (which are also `datetime.datetime` but without `tzinfo`). + +**Example usage** + +```python +import mgp + +@mgp.read_proc +def my_proc(ctx: mgp.ProcCtx, ts: mgp.ZonedDateTime) -> mgp.Record(result=mgp.ZonedDateTime): + return mgp.Record(result=ts) +``` + +## Enum + +```python +class Enum() +``` + +Represents an enum value with a type name and value name. + +Enum values can be received as procedure input and inspected, but cannot be returned +from procedures. + +| Property | Description | +| ------------ | -------------------------------------------------------------- | +| `type_name` | Returns the type name of the enum (e.g. `"Status"`). | +| `value_name` | Returns the value name of the enum (e.g. `"Active"`). | + +Enum objects support equality comparison and are hashable. + +**Example usage** + +```python +import mgp + +@mgp.read_proc +def inspect_enum(ctx: mgp.ProcCtx, val: mgp.Enum) -> mgp.Record(type_name=str, value_name=str): + return mgp.Record(type_name=val.type_name, value_name=val.value_name) +``` + ## Vertices Objects ```python From 67a5658efdf112a082f7d4287609d50fda6f0d45 Mon Sep 17 00:00:00 2001 From: imilinovic Date: Tue, 31 Mar 2026 14:37:21 +0200 Subject: [PATCH 2/2] docs: add missing C++ API entries for Point2d, Point3d, Enum Add Record::Insert and Result::SetValue overloads, Value constructors, and operator!= for Point2d/Point3d that were missed in the initial docs. --- pages/custom-query-modules/cpp/cpp-api.md | 42 +++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/pages/custom-query-modules/cpp/cpp-api.md b/pages/custom-query-modules/cpp/cpp-api.md index 454a7e927..a0c49e801 100644 --- a/pages/custom-query-modules/cpp/cpp-api.md +++ b/pages/custom-query-modules/cpp/cpp-api.md @@ -338,6 +338,18 @@ Inserts a value of given type under field `field_name`. void Insert(const char *field_name, const Duration value) ``` +```cpp + void Insert(const char *field_name, const Point2d &value) +``` + +```cpp + void Insert(const char *field_name, const Point3d &value) +``` + +```cpp + void Insert(const char *field_name, const Enum &value) +``` + ```cpp void Insert(const char *field_name, const Value &value) ``` @@ -431,6 +443,18 @@ Sets a return value of given type. void SetValue(const Duration &value) ``` +```cpp + void SetValue(const Point2d &value) +``` + +```cpp + void SetValue(const Point3d &value) +``` + +```cpp + void SetValue(const Enum &value) +``` + ##### SetErrorMessage Sets the given error message. @@ -1875,6 +1899,7 @@ std::string ToString() const | Name | Description | | ------------ | -------------------- | | `operator==` | comparison operator | +| `operator!=` | comparison operator | Object is hashable using @@ -1965,6 +1990,7 @@ std::string ToString() const | Name | Description | | ------------ | -------------------- | | `operator==` | comparison operator | +| `operator!=` | comparison operator | Object is hashable using @@ -2557,6 +2583,22 @@ explicit Value(const Duration &value) explicit Value(Duration &&value) ``` +Spatial type constructors: + +```cpp +explicit Value(const Point2d &value) +explicit Value(Point2d &&value) +explicit Value(const Point3d &value) +explicit Value(Point3d &&value) +``` + +Enum type constructors: + +```cpp +explicit Value(const Enum &value) +explicit Value(Enum &&value) +``` + Copy and move constructors: ```cpp