How to Fetch Different Kinds of Arguments in Apache AGE C-Language Functions
Tags: apacheage, postgres
Published: 2023-07-11 13:18:23

Creating a PostgreSQL extension in C, like [Apache AGE](https://age.apache.org/), allows you to execute high-performance code directly in your database. One of the challenges is passing arguments to these C functions. Here's a simple guide to fetch different kinds of arguments in a C-language function of a PostgreSQL extension.

Before we start, make sure to include necessary PostgreSQL headers in your C file:

```c
#include "postgres.h"
#include "fmgr.h"
#include "utils/builtins.h"
```

PostgreSQL provides the `fmgr` (Function Manager) module that includes macros for dealing with arguments. 

### Handling Scalar Arguments

For scalar arguments like integers or floats, use the `PG_GETARG_` macros:

```c
PG_FUNCTION_INFO_V1(add_integers);

Datum
add_integers(PG_FUNCTION_ARGS)
{
    int32 arg1 = PG_GETARG_INT32(0);  // Fetches the first argument
    int32 arg2 = PG_GETARG_INT32(1);  // Fetches the second argument

    PG_RETURN_INT32(arg1 + arg2);
}
```

### Handling String Arguments

For text arguments, use the `PG_GETARG_TEXT_P` macro:

```c
PG_FUNCTION_INFO_V1(echo_text);

Datum
echo_text(PG_FUNCTION_ARGS)
{
    text *arg1 = PG_GETARG_TEXT_P(0);
    char *cstr = text_to_cstring(arg1);

    PG_RETURN_TEXT_P(cstring_to_text(cstr));
}
```

### Handling Array Arguments

For arrays, use the `PG_GETARG_ARRAYTYPE_P` macro:

```c
PG_FUNCTION_INFO_V1(process_array);

Datum
process_array(PG_FUNCTION_ARGS)
{
    ArrayType *array = PG_GETARG_ARRAYTYPE_P(0);
    // Further processing...
}
```

### Handling NULL Arguments

You can check if an argument is NULL using `PG_ARGISNULL(index)` macro:

```c
PG_FUNCTION_INFO_V1(echo_or_default);

Datum
echo_or_default(PG_FUNCTION_ARGS)
{
    if (PG_ARGISNULL(0))
        PG_RETURN_TEXT_P(cstring_to_text("default"));
    else
    {
        text *arg1 = PG_GETARG_TEXT_P(0);
        char *cstr = text_to_cstring(arg1);

        PG_RETURN_TEXT_P(cstring_to_text(cstr));
    }
}
```

### Concluding Remarks

This is a basic guide to fetching arguments in PostgreSQL C functions. Depending on the argument's type, you will need to use the appropriate `PG_GETARG_` macros. Remember to consider NULL arguments as well. By mastering these techniques, you'll be able to harness the full power of PostgreSQL C-language functions.

Keep in mind that PostgreSQL's C API is vast and provides many more capabilities for dealing with complex data types, sets, and even triggering side effects on your database. Make sure to explore the [official PostgreSQL documentation](https://www.postgresql.org/docs/) for a more comprehensive understanding.

Note: C-language functions can offer significant performance advantages but come with risks, especially around memory management. Be sure to thoroughly test any C functions you write for your PostgreSQL database.

___

I make these posts in order to guide people into the development of a new technology. If you find anything incorrect, I urge you to comment below so I can fix it. Thanks!

___

Check Apache AGE: https://age.apache.org/.

Overview — Apache AGE master documentation: https://age.apache.org/age-manual/master/intro/overview.html.

GitHub - apache/age: https://github.com/apache/age