Open Source RDBMS - Seamless, Scalable, Stable and Free

한국어 | Login |Register

Versions available for this page: CUBRID 8.4.3 |  CUBRID 9.0.0 | 

Setting User-Defined Hash Function

To select a shard that will perform queries, the CUBRID SHARD uses the results of hashing the shard key and the metadata configuration information. For this, users can use the default hash function or define a hash function.

Default Hash Function

When the SHARD_KEY_LIBRARY_NAME and SHARD_KEY_FUNCTION_NAME parameters of shard.conf are not set, the shard key is hashed by using the default hash function. The default hash function is as follows:

  • When the shard_key is an integer
  • Default hash function (shard_key) = shard_key mod SHARD_KEY_MODULAR parameter (default value: 256)

  • When the shard_key is a string
  • Default hash function (shard_key) = shard_key[0] mod SHARD_KEY_MODULAR parameter (default value: 256)

Setting User-Defined Hash Function

The CUBRID SHARD can hash the shard key by using the user-defined hash function, in addition to the default hash function.

Implementing and Creating a Library

The user-defined hash function must be implemented as a .so library loadable at runtime. Its prototype is as shown below:

94 /*

95    return value :

96         success - shard key id(>0)

97         fail    - invalid argument(ERROR_ON_ARGUMENT), shard key id make fail(ERROR_ON_MAKE_SHARD_KEY)

98    type         : shard key value type

99    val          : shard key value

100 */

101 typedef int (*FN_GET_SHARD_KEY) (const char *shard_key, T_SHARD_U_TYPE type,

102                                    const void *val, int val_size);

  • The return value of the hash function should be within the range of the hash results of the shard_key.txt configuration file.
  • To build a library, the $CUBRID/include/shard_key.h file of the CUBRID source must be included. The file lets you know the details such as error code that can be returned.
Changing the shard.conf Configuration File

To apply a user-defined hash function, the SHARD_KEY_LIBRARY_NAME and SHARD_KEY_FUNCTION_NAME parameters of shard.conf should be set according to the implementation.

  • SHARD_KEY_LIBRARY_NAME: The (absolute) path of the user-defined hash library.
  • SHARD_KEY_FUNCTION_NAME: The name of the user-defined hash function.
Example

The following example shows how to use a user-defined hash.

First, check the shard_key.txt configuration file.

[%student_no]

#min    max     shard_id

0       31      0   

32      63      1   

64      95      2   

96      127     3   

128     159     0

160     191     1

192     223     2

224     255     3

To set the user-defined hash function, implement a .so shared library that is loadable at runtime. The result of the hash function should be within the range of hash function results defined in the shard_key.txt configuration file. The following example shows a simple implementation.

  • When the shard_key is an integer
    • Select shard #0 when the shard_key is an odd number
    • Select shard #1 when the shard_key is an even number
  • When the shard_key is a string
    • Select shard #0 when the shard_key string starts with 'a' or 'A'.
    • Select shard #1 when the shard_key string starts with 'b' or 'B'.
    • Select shard #2 when the shard_key string starts with 'c' or 'C'.
    • Select shard #3 when the shard_key string starts with 'd' or 'D'.

// <shard_key_udf.c>

 

1 #include <string.h>

2 #include <stdio.h>

3 #include <unistd.h>

4 #include "shard_key.h"

5

6 int

7 fn_shard_key_udf (const char *shard_key, T_SHARD_U_TYPE type,

8                   const void *value, int value_len)

9 {

10   unsigned int ival;

11   unsigned char c;

12

13   if (value == NULL)

14     {

15       return ERROR_ON_ARGUMENT;

16     }

17

18   switch (type)

19     {

20     case SHARD_U_TYPE_INT:

21       ival = (unsigned int) (*(unsigned int *) value);

22       if (ival % 2)

23         {

24           return 32;            // shard #1

25         }

26       else

27         {

28           return 0;             // shard #0

29         }

30       break;

31

32     case SHARD_U_TYPE_STRING:

33       c = (unsigned char) (((unsigned char *) value)[0]);

34       switch (c)

36         case 'a':

37         case 'A':

38           return 0;             // shard #0

39         case 'b':

40         case 'B':

41           return 32;            // shard #1

42         case 'c':

43         case 'C':

44           return 64;            // shard #2

45         case 'd':

46         case 'D':

47           return 96;            // shard #3

48         default:

49           return ERROR_ON_ARGUMENT;

50         }

51

52       break;

53

54     default:

55       return ERROR_ON_ARGUMENT;

56     }

57   return ERROR_ON_MAKE_SHARD_KEY;

58 }

Build the user-defined function as a shared library. The following example is Makefile for building a hash function.

# Makefile

 

CC = gcc

LIBS = $(LIB_FLAG)

CFLAGS = $(CFLAGS_COMMON) -fPIC -I$(CUBRID)/include –I$(CUBRID_SRC)/src/broker

 

SHARD_CC = gcc -g -shared -Wl,-soname,shard_key_udf.so

SHARD_KEY_UDF_OBJS = shard_key_udf.o

 

all:$(SHARD_KEY_UDF_OBJS)

        $(SHARD_CC) $(CFLAGS) -o shard_key_udf.so $(SHARD_KEY_UDF_OBJS) $(LIBS)

 

clean:

        -rm -f *.o core shard_key_udf.so

To include the user-defined hash function, modify the SHARD_KEY_LIBRARY_NAME and SHARD_KEY_FUNCTION_NAME parameters as shown in the above implementation.

[%student_no]

SHARD_KEY_LIBRARY_NAME     =$CUBRID/conf/shard_key_udf.so

SHARD_KEY_FUNCTION_NAME  =fn_shard_key_udf